Skip to main content

​
Overview

The MCP (Model Context Protocol) Server allows you to expose openbrowser’s browser automation capabilities to AI assistants like Claude Desktop, Cline, and other MCP-compatible clients. This enables AI assistants to perform web automation tasks directly through openbrowser.

​
Quick Start

​
Start MCP Server

uvx openbrowser --mcp
The server will start in stdio mode, ready to accept MCP connections.

​
Claude Desktop Integration

The most common use case is integrating with Claude Desktop. Add this configuration to your Claude Desktop config file:

​
macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "openbrowser-ai": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

​
Windows

Edit %APPDATA%\Claude\claude_desktop_config.json: 
{
  "mcpServers": {
    "openbrowser-ai": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

​
Environment Variables

You can configure openbrowser through environment variables:
  • OPENAI_API_KEY - Your OpenAI API key (required)
  • ANTHROPIC_API_KEY - Your Anthropic API key (alternative to OpenAI)
  • OPENBROWSER_HEADLESS - Set to false to show browser window
  • OPENBROWSER_DISABLE_SECURITY - Set to true to disable browser security features

​
Available Tools

The MCP server exposes these browser automation tools:

​
Autonomous Agent Tools

  • retry_with_openbrowser_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 with Claude Desktop, you can ask Claude 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 openbrowser repository, and tell me about the latest release"
Claude will use the MCP server to execute these tasks through openbrowser.

​
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():
    # Connect to openbrowser MCP server
    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 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

​
Common Issues

“MCP SDK is required” Error 
uv pip install '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
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

​
Debug Mode

Enable debug logging by setting: 
export OPENBROWSER_LOG_LEVEL=DEBUG
uvx openbrowser --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

​
Next Steps