Skip to main content

​
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] --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]", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}

​
Windows

Edit %APPDATA%\Claude\claude_desktop_config.json: 
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai[mcp]", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}

​
Claude Code

Add to your project’s .mcp.json: 
{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai[mcp]", "--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

CategoryFunctions
Navigationnavigate(url, new_tab), go_back(), wait(seconds)
Interactionclick(index), input_text(index, text, clear), scroll(down, pages, index), send_keys(keys), upload_file(index, path)
Dropdownsselect_dropdown(index, text), dropdown_options(index)
Tabsswitch(tab_id), close(tab_id)
JavaScriptevaluate(code) — run JS in page context, returns Python objects
Statebrowser.get_browser_state_summary() — page metadata and interactive elements
CSSget_selector_from_index(index) — CSS selector for an element
Completiondone(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]", "--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 
pip install 'openbrowser-ai[mcp]'
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] --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