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

# Browser Automation MCP

> Expose openbrowser capabilities via Model Context Protocol for AI assistants like Claude Desktop

## Overview

The MCP (Model Context Protocol) Server exposes OpenBrowser's browser automation as a single `execute_code` tool for AI assistants like Claude Desktop, Claude Code, and other MCP-compatible clients. The LLM writes Python code to navigate, interact with, and extract data from web pages. No external LLM API keys required -- the MCP client provides the intelligence.

## Quick Start

### Start MCP Server

```bash theme={null}
uvx openbrowser-ai --mcp
```

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

## Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"]
    }
  }
}
```

### Environment Variables

Optional configuration:

| Variable                          | Description                                        | Default |
| --------------------------------- | -------------------------------------------------- | ------- |
| `OPENBROWSER_HEADLESS`            | Run browser without GUI                            | `false` |
| `OPENBROWSER_ALLOWED_DOMAINS`     | Comma-separated domain whitelist                   | (none)  |
| `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (\~500 tokens vs \~1,430) | `false` |
| `OPENBROWSER_MAX_OUTPUT`          | Maximum output characters per execution            | `10000` |

## The `execute_code` Tool

The MCP server exposes a single tool that runs Python code in a persistent namespace with browser automation functions. All functions are async -- use `await`.

### Available Functions

| Category        | Functions                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Navigation**  | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)`                                                                        |
| **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |
| **Dropdowns**   | `select_dropdown(index, text)`, `dropdown_options(index)`                                                                     |
| **Tabs**        | `switch(tab_id)`, `close(tab_id)`                                                                                             |
| **JavaScript**  | `evaluate(code)` -- run JS in page context, returns Python objects                                                            |
| **State**       | `browser.get_browser_state_summary()` -- page metadata and interactive elements                                               |
| **CSS**         | `get_selector_from_index(index)` -- CSS selector for an element                                                               |
| **Completion**  | `done(text, success)` -- signal task completion                                                                               |

**Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`

Variables and state persist between `execute_code` calls within the same session.

## Example Usage

Once configured with Claude Desktop or Claude Code, you can ask the AI to perform browser automation tasks:

```
"Navigate to example.com and extract all the links"

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

"Go to GitHub, find the openbrowser repository, and tell me about the latest release"
```

The AI will use the `execute_code` tool to write Python code that navigates, interacts, and extracts data.

## 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():
    server_params = StdioServerParameters(
        command="uvx",
        args=["openbrowser-ai", "--mcp"]
    )

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

            # Navigate and extract page title
            result = await session.call_tool(
                "execute_code",
                arguments={"code": """
await navigate('https://example.com')
state = await browser.get_browser_state_summary()
print(f"Title: {state.title}")
print(f"URL: {state.url}")
"""}
            )
            print(result.content[0].text)

            # Extract data with JavaScript
            result = await session.call_tool(
                "execute_code",
                arguments={"code": """
links = await evaluate('Array.from(document.querySelectorAll("a")).map(a => ({text: a.textContent, href: a.href}))')
for link in links:
    print(f"{link['text']}: {link['href']}")
"""}
            )
            print(result.content[0].text)

asyncio.run(use_browser_mcp())
```

## CLI Execute Mode

For Bash-based workflows without an MCP client, use the [CLI Daemon](/customize/integrations/cli-daemon) instead. It provides the same `execute_code` functions via `openbrowser-ai -c "code"` with a persistent browser daemon.

## Troubleshooting

### Common Issues

**"MCP SDK is required" Error**

MCP is included in the base package since v0.1.30. Update to the latest version:

```bash theme={null}
pip install --upgrade openbrowser-ai
```

**Browser doesn't start**

* Check that you have Chrome/Chromium installed
* Try setting `OPENBROWSER_HEADLESS=false` to see browser window
* Ensure no other browser instances are using the same profile

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

### Debug Mode

Enable debug logging by setting:

```bash theme={null}
export OPENBROWSER_LOG_LEVEL=DEBUG
uvx openbrowser-ai --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
* Use `OPENBROWSER_ALLOWED_DOMAINS` to restrict navigation

## Next Steps

* Explore the [examples directory](https://github.com/billy-enrizky/openbrowser-ai/tree/main/examples/mcp) for more usage patterns
* Check out [MCP documentation](https://modelcontextprotocol.io/) to learn more about the protocol
* Join our [Discord](https://discord.gg/YRXzbJjq9K) for support and discussions