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:

// Example 1: One-Line Latest Version (Always Fresh)
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_GOOGLE_API_KEY": "YOUR_KEY_HERE_IF_USING_GOOGLE",
        "MCP_LLM_PROVIDER": "google",
        "MCP_LLM_MODEL_NAME": "gemini-2.5-flash-preview-04-17",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

// Example 2: Advanced Configuration with CDP
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "anthropic/claude-3.5-haiku",
        "MCP_LLM_TEMPERATURE": "0.4",

        "MCP_BROWSER_HEADLESS": "false",
        "MCP_BROWSER_WINDOW_WIDTH": "1440",
        "MCP_BROWSER_WINDOW_HEIGHT": "1080",
        "MCP_AGENT_TOOL_USE_VISION": "true",

        "MCP_RESEARCH_TOOL_SAVE_DIR": "/path/to/your/research",
        "MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS": "5",

        "MCP_PATHS_DOWNLOADS": "/path/to/your/downloads",

        "MCP_BROWSER_USE_OWN_BROWSER": "true",
        "MCP_BROWSER_CDP_URL": "http://localhost:9222",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 3: Advanced Configuration with User Data and custom chrome path
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        "MCP_LLM_PROVIDER": "openai",
        "MCP_LLM_MODEL_NAME": "gpt-4.1-mini",
        "MCP_LLM_TEMPERATURE": "0.2",

        "MCP_BROWSER_HEADLESS": "false",

        "MCP_BROWSER_BINARY_PATH": "/path/to/your/chrome/binary",
        "MCP_BROWSER_USER_DATA_DIR": "/path/to/your/user/data",
        "MCP_BROWSER_DISABLE_SECURITY": "true",
        "MCP_BROWSER_KEEP_OPEN": "true",
        "MCP_BROWSER_TRACE_PATH": "/path/to/your/trace",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 4: Local Development Flow
"mcpServers": {
    "browser-use": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/dev/path",
        "run",
        "mcp-server-browser-use"
      ],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "openai/gpt-4o-mini",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

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