> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browser-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> 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.

<Note>
  Looking for a hosted solution? Use the [Cloud MCP Server](/cloud/guides/mcp-server) instead — no setup required, just an API key.
</Note>

## Quick Start

```bash theme={null}
uvx --from 'browser-use[cli]' browser-use --mcp
```

The server will start in stdio mode, ready to accept MCP connections.

## Client Setup

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add browser-use -- uvx --from 'browser-use[cli]' browser-use --mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop config file:

    **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "browser-use": {
          "command": "/Users/your-username/.local/bin/uvx",
          "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
          "env": {
            "OPENAI_API_KEY": "your-openai-api-key-here"
          }
        }
      }
    }
    ```

    **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "browser-use": {
          "command": "uvx",
          "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
          "env": {
            "OPENAI_API_KEY": "your-openai-api-key-here"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.

    <Note>
      **macOS/Linux PATH Issue:** Claude Desktop may not find `uvx` in your PATH. Use the full path to `uvx` instead:

      * Run `which uvx` in your terminal to find the location (usually `/Users/username/.local/bin/uvx` or `~/.local/bin/uvx`)
      * Replace `"command": "uvx"` with the full path, e.g., `"command": "/Users/your-username/.local/bin/uvx"`
      * Replace `your-username` with your actual username

      **CLI Extras Required:** The `--from browser-use[cli]` flag installs the CLI extras needed for MCP server support.
    </Note>
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "browser-use": {
          "command": "uvx",
          "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
          "env": {
            "OPENAI_API_KEY": "your-openai-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "browser-use": {
          "command": "uvx",
          "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
          "env": {
            "OPENAI_API_KEY": "your-openai-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Environment Variables

* `OPENAI_API_KEY` - Your OpenAI API key (required)
* `ANTHROPIC_API_KEY` - Your Anthropic API key (alternative to OpenAI)
* `BROWSER_USE_HEADLESS` - Set to `false` to show browser window
* `BROWSER_USE_DISABLE_SECURITY` - Set to `true` to disable browser security features

## Available Tools

The local MCP server exposes these low-level browser automation tools for direct control:

#### Autonomous Agent Tools

* **`retry_with_browser_use_agent`** - Run a complete browser automation task with an AI agent (use as last resort when direct control fails)

#### Direct Browser Control

* **`browser_navigate`** - Navigate to a URL
* **`browser_click`** - Click on an element by index
* **`browser_type`** - Type text into an element
* **`browser_get_state`** - Get current page state and interactive elements
* **`browser_scroll`** - Scroll the page
* **`browser_go_back`** - Go back in browser history

#### Tab Management

* **`browser_list_tabs`** - List all open browser tabs
* **`browser_switch_tab`** - Switch to a specific tab
* **`browser_close_tab`** - Close a tab

#### Content Extraction

* **`browser_extract_content`** - Extract structured content from the current page

#### Session Management

* **`browser_list_sessions`** - List all active browser sessions with details
* **`browser_close_session`** - Close a specific browser session by ID
* **`browser_close_all`** - Close all active browser sessions

## Example Usage

Once configured, you can ask your AI to perform browser automation tasks:

```
"Please navigate to example.com and take a screenshot"

"Search for 'browser automation' on Google and summarize the first 3 results"

"Go to GitHub, find the browser-use repository, and tell me about the latest release"
```

## Programmatic Usage

You can also connect to the MCP server programmatically:

```python theme={null}
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def use_browser_mcp():
    # Connect to browser-use MCP server
    server_params = StdioServerParameters(
        command="uvx",
        args=["--from", "browser-use[cli]", "browser-use", "--mcp"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Navigate to a website
            result = await session.call_tool(
                "browser_navigate",
                arguments={"url": "https://example.com"}
            )
            print(result.content[0].text)

            # Get page state
            result = await session.call_tool(
                "browser_get_state",
                arguments={"include_screenshot": True}
            )
            print("Page state retrieved!")

asyncio.run(use_browser_mcp())
```

## Troubleshooting

**"CLI addon is not installed" Error**
Make sure you are using `--from 'browser-use[cli]'` in your uvx command:

```bash theme={null}
uvx --from 'browser-use[cli]' browser-use --mcp
```

**"spawn uvx ENOENT" Error (macOS/Linux)**
Claude Desktop cannot find `uvx` in its PATH. Use the full path in your config:

* Run `which uvx` in terminal to find the location
* Update your config to use the full path (e.g., `/Users/your-username/.local/bin/uvx`)

**Browser doesn't start**

* Check that you have Chrome/Chromium installed
* Try setting `BROWSER_USE_HEADLESS=false` to see browser window
* 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

**Connection Issues in Claude Desktop**

* Restart Claude Desktop after config changes
* Check the config file syntax is valid JSON
* Verify the file path is correct for your OS
* Check logs at `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\Logs\` (Windows)

**Debug Mode**

Enable debug logging by setting:

```bash theme={null}
export BROWSER_USE_LOGGING_LEVEL=DEBUG
uvx --from 'browser-use[cli]' browser-use --mcp
```

## Security Considerations

* The MCP server has access to your browser and file system
* Only connect trusted MCP clients
* Be cautious with sensitive websites and data
* Consider running in a sandboxed environment for untrusted automation

## Next Steps

* Explore the [examples directory](https://github.com/browser-use/browser-use/tree/main/examples) for more usage patterns
* Check out [MCP documentation](https://modelcontextprotocol.io/) to learn more about the protocol
* Join our [Discord](https://link.browser-use.com/discord) for support and discussions