Browser-Use MCP Server

browser-use MCP server & CLI

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.

AI-driven browser automation server implementing the Model Context Protocol (MCP) for natural language browser control and web research. Also provides CLI access to its core functionalities.

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 server 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_research tool).
• ⚙️ Environment Variable Configuration - Fully configurable via environment variables using a structured Pydantic model.
• 🔗 CDP Connection - Ability to connect to and control a user-launched Chrome/Chromium instance via Chrome DevTools Protocol.
• ⌨️ CLI Interface - Access core agent functionalities (run_browser_agent, run_deep_research) directly from the command line for testing and scripting.

Quick Start

The Essentials

1. Install UV - the rocket-powered Python installer: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Get Playwright browsers (required for automation): uvx --from mcp-server-browser-use@latest python -m playwright install

Integration Patterns

For MCP clients like Claude Desktop, add a server configuration that's as simple as:

Key Insight: The best configurations emerge from starting simple (Example 1). The .env.example file contains all possible dials.

MCP Tools

This server exposes the following tools via the Model Context Protocol:

Synchronous Tools (Wait for Completion)

1. run_browser_agent
   • Description: Executes a browser automation task based on natural language instructions and waits for it to complete. Uses settings from MCP_AGENT_TOOL_*, MCP_LLM_*, and MCP_BROWSER_* environment variables.
   • Arguments:
     • task (string, required): The primary task or objective.
   • Returns: (string) The final result extracted by the agent or an error message. Agent history (JSON, optional GIF) saved if MCP_AGENT_TOOL_HISTORY_PATH is set.
2. run_deep_research
   • Description: Performs in-depth web research on a topic, generates a report, and waits for completion. Uses settings from MCP_RESEARCH_TOOL_*, MCP_LLM_*, and MCP_BROWSER_* environment variables. If MCP_RESEARCH_TOOL_SAVE_DIR is set, outputs are saved to a subdirectory within it; otherwise, operates in memory-only mode.
   • Arguments:
     • research_task (string, required): The topic or question for the research.
     • max_parallel_browsers (integer, optional): Overrides MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS from environment.
   • Returns: (string) The generated research report in Markdown format, including the file path (if saved), or an error message.

CLI Usage

This package also provides a command-line interface mcp-browser-cli for direct testing and scripting.

Global Options:

• --env-file PATH, -e PATH: Path to a .env file to load configurations from.
• --log-level LEVEL, -l LEVEL: Override the logging level (e.g., DEBUG, INFO).

Commands:

1. mcp-browser-cli run-browser-agent [OPTIONS] TASK
   • Description: Runs a browser agent task.
   • Arguments:
     • TASK (string, required): The primary task for the agent.
   • Example:
     mcp-browser-cli run-browser-agent "Go to example.com and find the title." -e .env
2. mcp-browser-cli run-deep-research [OPTIONS] RESEARCH_TASK
   • Description: Performs deep web research.
   • Arguments:
     • RESEARCH_TASK (string, required): The topic or question for research.
   • Options:
     • --max-parallel-browsers INTEGER, -p INTEGER: Override MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS.
   • Example:
     mcp-browser-cli run-deep-research "What are the latest advancements in AI-driven browser automation?" --max-parallel-browsers 5 -e .env

All other configurations (LLM keys, paths, browser settings) are picked up from environment variables (or the specified .env file) as detailed in the Configuration section.

Configuration (Environment Variables)

Configure the server and CLI using environment variables. You can set these in your system or place them in a .env file in the project root (use --env-file for CLI). Variables are structured with prefixes.

Supported LLM Providers (MCP_LLM_PROVIDER): openai, azure_openai, anthropic, google, mistral, ollama, deepseek, openrouter, alibaba, moonshot, unbound

(Refer to .env.example for a comprehensive list of all supported environment variables and their specific provider keys/endpoints.)

Connecting to Your Own Browser (CDP)

Instead of having the server launch and manage its own browser instance, you can connect it to a Chrome/Chromium browser that you launch and manage yourself.

Steps:

1. Launch Chrome/Chromium with Remote Debugging Enabled: (Commands for macOS, Linux, Windows as previously listed, e.g., google-chrome --remote-debugging-port=9222)
2. Configure Environment Variables: Set the following environment variables:
   MCP_BROWSER_USE_OWN_BROWSER=true MCP_BROWSER_CDP_URL=http://localhost:9222 # Use the same port # Optional: MCP_BROWSER_USER_DATA_DIR=/path/to/your/profile
3. Run the MCP Server or CLI: Start the server (uv run mcp-server-browser-use) or CLI (mcp-browser-cli ...) as usual.

Important Considerations:

• The browser launched with --remote-debugging-port must remain open.
• Settings like MCP_BROWSER_HEADLESS and MCP_BROWSER_KEEP_OPEN are ignored when MCP_BROWSER_USE_OWN_BROWSER=true.

Development

Troubleshooting

• Configuration Error on Startup: If the application fails to start with an error about a missing setting, ensure all mandatory environment variables (like MCP_RESEARCH_TOOL_SAVE_DIR) are set correctly in your environment or .env file.
• Browser Conflicts: If not using CDP (MCP_BROWSER_USE_OWN_BROWSER=false), ensure no conflicting Chrome instances are running with the same user data directory if MCP_BROWSER_USER_DATA_DIR is specified.
• CDP Connection Issues: If using MCP_BROWSER_USE_OWN_BROWSER=true:
  • Verify Chrome was launched with --remote-debugging-port.
  • Ensure the port in MCP_BROWSER_CDP_URL matches.
  • Check firewalls and ensure the browser is running.
• API Errors: Double-check API keys (MCP_LLM_<PROVIDER>_API_KEY or MCP_LLM_API_KEY) and endpoints (e.g., MCP_LLM_AZURE_OPENAI_ENDPOINT for Azure).
• Vision Issues: Ensure MCP_AGENT_TOOL_USE_VISION=true and your LLM supports vision.
• Dependency Problems: Run uv sync and uv run playwright install.
• File/Path Issues:
  • If optional features like history saving, tracing, or downloads are not working, ensure the corresponding path variables (MCP_AGENT_TOOL_HISTORY_PATH, MCP_BROWSER_TRACE_PATH, MCP_PATHS_DOWNLOADS) are set and the application has write permissions to those locations.
  • For deep research, ensure MCP_RESEARCH_TOOL_SAVE_DIR is set to a valid, writable directory.
• Logging: Check the log file (MCP_SERVER_LOG_FILE, if set) or console output. Increase MCP_SERVER_LOGGING_LEVEL to DEBUG for more details. For CLI, use --log-level DEBUG.

License

MIT - See LICENSE for details.