browser-use MCP server

Project Note: This MCP server implementation builds upon the browser-use/web-ui foundation. Core browser automation logic and configuration patterns are adapted from the original project.

Features

• **MCP Integration** - Full protocol implementation for AI agent communication.

• **Browser Automation** - Page navigation, form filling, element interaction via natural language (`run_browser_agent` tool).

• **Visual Understanding** - Optional screenshot analysis for vision-capable LLMs.

• **State Persistence** - Option to manage a browser session across multiple MCP calls or connect to user's browser.

• **Multi-LLM Support** - Integrates with OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.

• **Deep Research Tool** - Dedicated tool for multi-step web research and report generation (`run_deep_search` tool).

• **Environment Variable Configuration** - Fully configurable via environment variables.

• **CDP Connection** - Ability to connect to and control a user-launched Chrome/Chromium instance via Chrome DevTools Protocol.

Quick Start

Prerequisites

• Python 3.11 or higher

• uv (fast Python package installer): pip install uv

• Chrome/Chromium browser installed

• Install Playwright browsers: uv sync and then uv run playwright install

Integration with MCP Clients (e.g., Claude Desktop)

MCP Tools

Synchronous Tools (Wait for Completion)

1. `run_browser_agent`

2. `run_deep_search`

Configuration (Environment Variables)

Connecting to Your Own Browser (CDP)

• Using your existing browser profile (cookies, logins, extensions).

• Observing the automation directly in your own browser window.

• Debugging complex scenarios.

1. Launch Chrome/Chromium with Remote Debugging Enabled: Open your terminal or command prompt and run the command appropriate for your operating system. This tells Chrome to listen for connections on a specific port (e.g., 9222).Note: If port 9222 is already in use, choose a different port (e.g., 9223) and use that same port in the CHROME_CDP environment variable.

2. Configure Environment Variables: Set the following environment variables in your .env file or system environment before starting the MCP server:

3. Run the MCP Server: Start the server as usual:

• The browser launched with --remote-debugging-port must remain open while the MCP server is running and needs to interact with it.

• Ensure the CHROME_CDP URL is accessible from where the MCP server is running (usually http://localhost:PORT if running on the same machine).

• Using your own browser means the server inherits its state (open tabs, logged-in sessions). Be mindful of this during automation.

• Settings like MCP_HEADLESS, BROWSER_HEADLESS, MCP_KEEP_BROWSER_OPEN are ignored when MCP_USE_OWN_BROWSER=true. Window size is determined by your browser window.

Development

Troubleshooting

• Browser Conflicts: If not using CHROME_CDP (MCP_USE_OWN_BROWSER=false), ensure no other conflicting Chrome instances are running with the same user data directory if CHROME_USER_DATA is specified.

• CDP Connection Issues: If using MCP_USE_OWN_BROWSER=true:

• API Errors: Double-check that the correct API key environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) is set for your chosen MCP_MODEL_PROVIDER, or that MCP_API_KEY is set. Verify keys and endpoints (AZURE_OPENAI_ENDPOINT is required for Azure).

• Vision Issues: Ensure MCP_USE_VISION=true if using vision features and that your selected LLM model supports vision.

• Dependency Problems: Run uv sync to ensure all dependencies are correctly installed. Check pyproject.toml.

• Logging: Check the log file specified by LOG_FILE (default: mcp_server_browser_use.log) for detailed error messages. Increase BROWSER_USE_LOGGING_LEVEL to DEBUG for more verbose output.

License

browser-use MCP server

Project Note: This MCP server implementation builds upon the browser-use/web-ui foundation. Core browser automation logic and configuration patterns are adapted from the original project.

Features

• **MCP Integration** - Full protocol implementation for AI agent communication.

• **Browser Automation** - Page navigation, form filling, element interaction via natural language (`run_browser_agent` tool).

• **Visual Understanding** - Optional screenshot analysis for vision-capable LLMs.

• **State Persistence** - Option to manage a browser session across multiple MCP calls or connect to user's browser.

• **Multi-LLM Support** - Integrates with OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.

• **Deep Research Tool** - Dedicated tool for multi-step web research and report generation (`run_deep_search` tool).

• **Environment Variable Configuration** - Fully configurable via environment variables.

• **CDP Connection** - Ability to connect to and control a user-launched Chrome/Chromium instance via Chrome DevTools Protocol.

Quick Start

Prerequisites

• Python 3.11 or higher

• uv (fast Python package installer): pip install uv

• Chrome/Chromium browser installed

• Install Playwright browsers: uv sync and then uv run playwright install

Integration with MCP Clients (e.g., Claude Desktop)

MCP Tools

Synchronous Tools (Wait for Completion)

1. `run_browser_agent`

2. `run_deep_search`

Configuration (Environment Variables)

Connecting to Your Own Browser (CDP)

• Using your existing browser profile (cookies, logins, extensions).

• Observing the automation directly in your own browser window.

• Debugging complex scenarios.

1. Launch Chrome/Chromium with Remote Debugging Enabled: Open your terminal or command prompt and run the command appropriate for your operating system. This tells Chrome to listen for connections on a specific port (e.g., 9222).Note: If port 9222 is already in use, choose a different port (e.g., 9223) and use that same port in the CHROME_CDP environment variable.

2. Configure Environment Variables: Set the following environment variables in your .env file or system environment before starting the MCP server:

3. Run the MCP Server: Start the server as usual:

• The browser launched with --remote-debugging-port must remain open while the MCP server is running and needs to interact with it.

• Ensure the CHROME_CDP URL is accessible from where the MCP server is running (usually http://localhost:PORT if running on the same machine).

• Using your own browser means the server inherits its state (open tabs, logged-in sessions). Be mindful of this during automation.

• Settings like MCP_HEADLESS, BROWSER_HEADLESS, MCP_KEEP_BROWSER_OPEN are ignored when MCP_USE_OWN_BROWSER=true. Window size is determined by your browser window.

Development

Troubleshooting

• Browser Conflicts: If not using CHROME_CDP (MCP_USE_OWN_BROWSER=false), ensure no other conflicting Chrome instances are running with the same user data directory if CHROME_USER_DATA is specified.

• CDP Connection Issues: If using MCP_USE_OWN_BROWSER=true:

• API Errors: Double-check that the correct API key environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) is set for your chosen MCP_MODEL_PROVIDER, or that MCP_API_KEY is set. Verify keys and endpoints (AZURE_OPENAI_ENDPOINT is required for Azure).

• Vision Issues: Ensure MCP_USE_VISION=true if using vision features and that your selected LLM model supports vision.

• Dependency Problems: Run uv sync to ensure all dependencies are correctly installed. Check pyproject.toml.

• Logging: Check the log file specified by LOG_FILE (default: mcp_server_browser_use.log) for detailed error messages. Increase BROWSER_USE_LOGGING_LEVEL to DEBUG for more verbose output.

License