Browser Automation MCP

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

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:

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

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Claude Code

Add to your project’s .mcp.json:

{
  "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:

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

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:

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 for more usage patterns
Check out MCP documentation to learn more about the protocol
Join our Discord for support and discussions

Get Started

Customize

Examples

Development

Browser Automation MCP

Overview

Quick Start

Start MCP Server

Claude Desktop Integration

macOS

Windows

Claude Code

Environment Variables

The `execute_code` Tool

Available Functions

Example Usage

Programmatic Usage

CLI Execute Mode

Troubleshooting

Common Issues

Debug Mode

Security Considerations

Next Steps

​Overview

​Quick Start

​Start MCP Server

​Claude Desktop Integration

​macOS

​Windows

​Claude Code

​Environment Variables

​The execute_code Tool

​Available Functions

​Example Usage

​Programmatic Usage

​CLI Execute Mode

​Troubleshooting

​Common Issues

​Debug Mode

​Security Considerations

​Next Steps

Overview

Quick Start

Start MCP Server

Claude Desktop Integration

macOS

Windows

Claude Code

Environment Variables

The `execute_code` Tool

Available Functions

Example Usage

Programmatic Usage

CLI Execute Mode

Troubleshooting

Common Issues

Debug Mode

Security Considerations

Next Steps