Skip to content

docs: state local MCP key requirements exactly #251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MagMueller wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: state local MCP key requirements exactly #251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b068ec1
docs: state local MCP key requirements exactly
MagMueller Sep 5, 2026
aea0f99
Merge commit '46a83913f8b3c4193dd5d836eeb84467c04eafd8' into agency/m…
MagMueller Sep 7, 2026
0dd6694
docs: separate direct MCP controls from optional model setup
MagMueller Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 34 additions & 6 deletions docs/open-source/customize/integrations/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: "MCP Server"
description: "Run browser-use as a local Model Context Protocol server. Connect AI models to browser automation through the MCP standard."
---

Browser Use can run as a local **Model Context Protocol (MCP)** server on your machine via stdio. This is the **free, open-source option** that gives you direct, low-level control over browser automation but requires your own LLM API keys.
Connect your MCP client to Browser Use running locally on your machine. The free, open-source server lets your AI navigate, click, type and inspect pages. Direct browser control needs no LLM API key in the server.

<Note>
Looking for a hosted solution? Use the [Cloud MCP Server](/cloud/guides/mcp-server) instead — no setup required, just an API key.
Expand Down Expand Up @@ -107,13 +107,42 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
</Tab>
</Tabs>

## Model keys

Your MCP client supplies the AI for direct browser control. Two optional tools ask the server to call a model itself:

| What you call | What the server needs |
| --- | --- |
| Direct browser tools: navigate, click, type, state, HTML, screenshot | No LLM key |
| `browser_extract_content`: turn page content into structured data | An OpenAI-compatible key |
| `retry_with_browser_use_agent`: hand a complete task to a separate browser agent | An OpenAI-compatible key, or the Bedrock setup below |

The last row is an existing tool name, not an automatic retry of every browser action.

## Environment Variables

- `OPENAI_API_KEY` - Your OpenAI API key (required)
- `ANTHROPIC_API_KEY` - Your Anthropic API key (alternative to OpenAI)
- `OPENAI_API_KEY` - Required for extraction and the default autonomous agent. Omit it from the client configurations above if you only use direct browser tools
- `BROWSER_USE_HEADLESS` - Set to `false` to show browser window
- `BROWSER_USE_DISABLE_SECURITY` - Set to `true` to disable browser security features

### AWS Bedrock agent setup

For the optional autonomous agent tool, use `browser-use[cli,aws]` instead of `browser-use[cli]` in your MCP client's command arguments. This installs the required AWS dependency:

```bash
uvx --from 'browser-use[cli,aws]' browser-use --mcp
```

Set these in the MCP server's environment:

- `MODEL_PROVIDER=bedrock` - Select Bedrock for the autonomous agent
- `BROWSER_USE_LLM_MODEL` - A Bedrock model or inference-profile ID available to your AWS account and region. This overrides the saved model; `MODEL` alone does not override it
- `REGION` - Your Bedrock region, for example `us-east-1`. The MCP agent defaults to `us-east-1`; `AWS_DEFAULT_REGION` does not override this choice
- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - Your AWS credentials with access to the chosen Bedrock model
- `AWS_SESSION_TOKEN` - Also set this when using temporary AWS credentials

This setup does not need `OPENAI_API_KEY` for the autonomous agent. It does not configure `browser_extract_content` for Bedrock; extraction still uses the separate OpenAI-compatible LLM path.

## Available Tools

The local MCP server exposes these low-level browser automation tools for direct control:
Expand Down Expand Up @@ -212,9 +241,8 @@ Claude Desktop cannot find `uvx` in its PATH. Use the full path in your config:
- Ensure no other browser instances are using the same profile

**API Key Issues**
- Verify your `OPENAI_API_KEY` is set correctly
- Check API key permissions and billing status
- Try using `ANTHROPIC_API_KEY` as an alternative
- Direct browser tools such as navigate, click, type, page state, HTML, and screenshot do not require a key
- For `browser_extract_content` or the default OpenAI-compatible agent route, verify that `OPENAI_API_KEY` is set and has billing enabled

**Connection Issues in Claude Desktop**
- Restart Claude Desktop after config changes
Expand Down
40 changes: 34 additions & 6 deletions docs/open-source/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2883,7 +2883,7 @@ def finish_task() -> ActionResult:
Source: https://docs.browser-use.com/open-source/customize/integrations/mcp-server


Browser Use can run as a local **Model Context Protocol (MCP)** server on your machine via stdio. This is the **free, open-source option** that gives you direct, low-level control over browser automation but requires your own LLM API keys.
Connect your MCP client to Browser Use running locally on your machine. The free, open-source server lets your AI navigate, click, type and inspect pages. Direct browser control needs no LLM API key in the server.

Looking for a hosted solution? Use the [Cloud MCP Server](https://docs.browser-use.com/cloud/guides/mcp-server) instead — no setup required, just an API key.

Expand Down Expand Up @@ -2973,13 +2973,42 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
}
```

## Model keys

Your MCP client supplies the AI for direct browser control. Two optional tools ask the server to call a model itself:

| What you call | What the server needs |
| --- | --- |
| Direct browser tools: navigate, click, type, state, HTML, screenshot | No LLM key |
| `browser_extract_content`: turn page content into structured data | An OpenAI-compatible key |
| `retry_with_browser_use_agent`: hand a complete task to a separate browser agent | An OpenAI-compatible key, or the Bedrock setup below |

The last row is an existing tool name, not an automatic retry of every browser action.

## Environment Variables

- `OPENAI_API_KEY` - Your OpenAI API key (required)
- `ANTHROPIC_API_KEY` - Your Anthropic API key (alternative to OpenAI)
- `OPENAI_API_KEY` - Required for extraction and the default autonomous agent. Omit it from the client configurations above if you only use direct browser tools

@cubic-dev-ai cubic-dev-ai Bot Sep 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The new OPENAI_API_KEY line says the key is 'Required for extraction', but the Available Tools list groups browser_get_html and browser_screenshot under 'Content Extraction' even though they need no key (as the Model keys table states). A reader who uses get_html/screenshot and sees them under 'Content Extraction' may conclude they need the key. Narrow the wording to the one tool that requires it.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At docs/open-source/llms-full.txt, line 2990:

<comment>The new OPENAI_API_KEY line says the key is 'Required for extraction', but the Available Tools list groups browser_get_html and browser_screenshot under 'Content Extraction' even though they need no key (as the Model keys table states). A reader who uses get_html/screenshot and sees them under 'Content Extraction' may conclude they need the key. Narrow the wording to the one tool that requires it.</comment>

<file context>
@@ -2973,12 +2973,42 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 ## Environment Variables
 
-- `OPENAI_API_KEY` - Optional for direct browser control; required for `browser_extract_content` and the default OpenAI-compatible route of `retry_with_browser_use_agent`
+- `OPENAI_API_KEY` - Required for extraction and the default autonomous agent. Omit it from the client configurations above if you only use direct browser tools
 - `BROWSER_USE_HEADLESS` - Set to `false` to show browser window
 - `BROWSER_USE_DISABLE_SECURITY` - Set to `true` to disable browser security features
</file context>
Suggested change
- `OPENAI_API_KEY` - Required for extraction and the default autonomous agent. Omit it from the client configurations above if you only use direct browser tools
- `OPENAI_API_KEY` - Required for `browser_extract_content` and the default autonomous agent. Omit it from the client configurations above if you only use direct browser tools
Fix with cubic

- `BROWSER_USE_HEADLESS` - Set to `false` to show browser window
- `BROWSER_USE_DISABLE_SECURITY` - Set to `true` to disable browser security features

### AWS Bedrock agent setup

For the optional autonomous agent tool, use `browser-use[cli,aws]` instead of `browser-use[cli]` in your MCP client's command arguments. This installs the required AWS dependency:

```bash
uvx --from 'browser-use[cli,aws]' browser-use --mcp
```

Set these in the MCP server's environment:

- `MODEL_PROVIDER=bedrock` - Select Bedrock for the autonomous agent
- `BROWSER_USE_LLM_MODEL` - A Bedrock model or inference-profile ID available to your AWS account and region. This overrides the saved model; `MODEL` alone does not override it
- `REGION` - Your Bedrock region, for example `us-east-1`. The MCP agent defaults to `us-east-1`; `AWS_DEFAULT_REGION` does not override this choice
- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` - Your AWS credentials with access to the chosen Bedrock model
- `AWS_SESSION_TOKEN` - Also set this when using temporary AWS credentials

This setup does not need `OPENAI_API_KEY` for the autonomous agent. It does not configure `browser_extract_content` for Bedrock; extraction still uses the separate OpenAI-compatible LLM path.

## Available Tools

The local MCP server exposes these low-level browser automation tools for direct control:
Expand Down Expand Up @@ -3078,9 +3107,8 @@ Claude Desktop cannot find `uvx` in its PATH. Use the full path in your config:
- Ensure no other browser instances are using the same profile

**API Key Issues**
- Verify your `OPENAI_API_KEY` is set correctly
- Check API key permissions and billing status
- Try using `ANTHROPIC_API_KEY` as an alternative
- Direct browser tools such as navigate, click, type, page state, HTML, and screenshot do not require a key
- For `browser_extract_content` or the default OpenAI-compatible agent route, verify that `OPENAI_API_KEY` is set and has billing enabled

**Connection Issues in Claude Desktop**
- Restart Claude Desktop after config changes
Expand Down