Skip to content

Saik0s/mcp-browser-use

BranchesTags

Repository files navigation

Browser Use Web UI


browser-use MCP server & CLI

Documentation License

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.

Browser-Use MCP server

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

Variable Group (Prefix) Example Variable Description Default Value
Main LLM (MCP_LLM_) Settings for the primary LLM used by agents.
MCP_LLM_PROVIDER LLM provider. Options: openai, azure_openai, anthropic, google, mistral, ollama, etc. openai
MCP_LLM_MODEL_NAME Specific model name for the provider. gpt-4.1
MCP_LLM_TEMPERATURE LLM temperature (0.0-2.0). 0.0
MCP_LLM_BASE_URL Optional: Generic override for LLM provider's base URL. Provider-specific
MCP_LLM_API_KEY Optional: Generic LLM API key (takes precedence). -
MCP_LLM_OPENAI_API_KEY API Key for OpenAI (if provider is openai). -
MCP_LLM_ANTHROPIC_API_KEY API Key for Anthropic. -
MCP_LLM_GOOGLE_API_KEY API Key for Google AI (Gemini). -
MCP_LLM_AZURE_OPENAI_API_KEY API Key for Azure OpenAI. -
MCP_LLM_AZURE_OPENAI_ENDPOINT Required if using Azure. Your Azure resource endpoint. -
MCP_LLM_OLLAMA_ENDPOINT Ollama API endpoint URL. http://localhost:11434
MCP_LLM_OLLAMA_NUM_CTX Context window size for Ollama models. 32000
Planner LLM (MCP_LLM_PLANNER_) Optional: Settings for a separate LLM for agent planning. Defaults to Main LLM if not set.
MCP_LLM_PLANNER_PROVIDER Planner LLM provider. Main LLM Provider
MCP_LLM_PLANNER_MODEL_NAME Planner LLM model name. Main LLM Model
Browser (MCP_BROWSER_) General browser settings.
MCP_BROWSER_HEADLESS Run browser without UI (general setting). false
MCP_BROWSER_DISABLE_SECURITY Disable browser security features (general setting, use cautiously). false
MCP_BROWSER_BINARY_PATH Path to Chrome/Chromium executable. -
MCP_BROWSER_USER_DATA_DIR Path to Chrome user data directory. -
MCP_BROWSER_WINDOW_WIDTH Browser window width (pixels). 1280
MCP_BROWSER_WINDOW_HEIGHT Browser window height (pixels). 1080
MCP_BROWSER_USE_OWN_BROWSER Connect to user's browser via CDP URL. false
MCP_BROWSER_CDP_URL CDP URL (e.g., http://localhost:9222). Required if MCP_BROWSER_USE_OWN_BROWSER=true. -
MCP_BROWSER_KEEP_OPEN Keep server-managed browser open between MCP calls (if MCP_BROWSER_USE_OWN_BROWSER=false). false
MCP_BROWSER_TRACE_PATH Optional: Directory to save Playwright trace files. If not set, tracing to file is disabled. (empty, tracing disabled)
Agent Tool (MCP_AGENT_TOOL_) Settings for the run_browser_agent tool.
MCP_AGENT_TOOL_MAX_STEPS Max steps per agent run. 100
MCP_AGENT_TOOL_MAX_ACTIONS_PER_STEP Max actions per agent step. 5
MCP_AGENT_TOOL_TOOL_CALLING_METHOD Method for tool invocation ('auto', 'json_schema', 'function_calling'). auto
MCP_AGENT_TOOL_MAX_INPUT_TOKENS Max input tokens for LLM context. 128000
MCP_AGENT_TOOL_USE_VISION Enable vision capabilities (screenshot analysis). true
MCP_AGENT_TOOL_HEADLESS Override MCP_BROWSER_HEADLESS for this tool (true/false/empty). (uses general)
MCP_AGENT_TOOL_DISABLE_SECURITY Override MCP_BROWSER_DISABLE_SECURITY for this tool (true/false/empty). (uses general)
MCP_AGENT_TOOL_ENABLE_RECORDING Enable Playwright video recording. false
MCP_AGENT_TOOL_SAVE_RECORDING_PATH Optional: Path to save recordings. If not set, recording to file is disabled even if ENABLE_RECORDING=true. (empty, recording disabled)
MCP_AGENT_TOOL_HISTORY_PATH Optional: Directory to save agent history JSON files. If not set, history saving is disabled. (empty, history saving disabled)
Research Tool (MCP_RESEARCH_TOOL_) Settings for the run_deep_research tool.
MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS Max parallel browser instances for deep research. 3
MCP_RESEARCH_TOOL_SAVE_DIR Optional: Base directory to save research artifacts. Task ID will be appended. If not set, operates in memory-only mode. None
Paths (MCP_PATHS_) General path settings.
MCP_PATHS_DOWNLOADS Optional: Directory for downloaded files. If not set, persistent downloads to a specific path are disabled. (empty, downloads disabled)
Server (MCP_SERVER_) Server-specific settings.
MCP_SERVER_LOG_FILE Path for the server log file. Empty for stdout. (empty, logs to stdout)
MCP_SERVER_LOGGING_LEVEL Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). ERROR
MCP_SERVER_ANONYMIZED_TELEMETRY Enable/disable anonymized telemetry (true/false). true
MCP_SERVER_MCP_CONFIG Optional: JSON string for MCP client config used by the internal controller. null

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

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run MCP server with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222 --user-data-dir="optional/path/to/user/profile"
# 2. Run inspector command with environment variables:
npx @modelcontextprotocol/inspector@latest \
  -e MCP_LLM_GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -e MCP_LLM_PROVIDER=google \
  -e MCP_LLM_MODEL_NAME=gemini-2.5-flash-preview-04-17 \
  -e MCP_BROWSER_USE_OWN_BROWSER=true \
  -e MCP_BROWSER_CDP_URL=http://localhost:9222 \
  -e MCP_RESEARCH_TOOL_SAVE_DIR=./tmp/dev_research_output \
  uv --directory . run mcp-server-browser-use

# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

# Run CLI example
# Create a .env file with your settings (including MCP_RESEARCH_TOOL_SAVE_DIR) or use environment variables
uv run mcp-browser-cli -e .env run-browser-agent "What is the title of example.com?"
uv run mcp-browser-cli -e .env run-deep-research "What is the best material for a pan for everyday use on amateur kitchen and dishwasher?"

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.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

651 stars

Watchers

3 watching

Forks

83 forks
Report repository

Releases

10 tags

Packages

No packages published

Contributors 6

Languages