---
title: "Browser Automation MCP"
description: "Expose openbrowser capabilities via Model Context Protocol for AI assistants like Claude Desktop"
icon: "server"
mode: "wide"
---

## 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
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
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}
```

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

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

### Claude Code

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

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

### Environment Variables

Optional configuration:

- `OPENBROWSER_HEADLESS` - Set to `true` to run browser without GUI (default: `false`)
- `OPENBROWSER_ALLOWED_DOMAINS` - Comma-separated domain whitelist

## 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
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())
```

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