MCP Browser Use Server

Model Context Protocol (MCP) server that wires browser-use into Claude Desktop and other MCP compatible clients.

Overview

This repository provides a beta MCP wrapper around the browser-use automation engine. It exposes a single MCP tool (run_browser_agent) that orchestrates a browser session, executes the browser-use agent, and returns the final result to the client. The layout keeps configuration in one place, makes security boundaries testable, and isolates upstream browser-use migrations from the MCP interface.

Key Capabilities

• Automated browsing – Navigate, interact with forms, control tabs, capture screenshots, and read page content through natural-language instructions executed by browser-use.
• Agent lifecycle management – CustomAgent wraps browser-use's base agent to add history export, richer prompts, and consistent error handling across runs.
• Centralised browser configuration – create_browser_session translates environment variables into a ready-to-use BrowserSession, enabling persistent profiles, proxies, and custom Chromium flags without touching the agent logic.
• FastMCP integration – server.py registers the MCP tool, normalises configuration, and ensures the browser session is always cleaned up.
• Client helpers – client.py includes async helpers for tests or other Python processes that wish to exercise the MCP server in-process.

Project Structure

.
├── documentation/
│   ├── CONFIGURATION.md      # Detailed configuration reference
│   └── SECURITY.md           # Security considerations for running the server
├── sample.env.env           # Example environment variables for local development
├── src/mcp_browser_use/
│   ├── agent/                # Custom agent, prompts, message history, and views
│   ├── browser/              # Browser session factory and persistence helpers
│   ├── controller/           # Custom controller extensions for clipboard actions
│   ├── utils/                # LLM factory, agent state helpers, encoding utilities
│   ├── client.py             # Async helper for connecting to the FastMCP app
│   └── server.py             # FastMCP app and the `run_browser_agent` tool
└── tests/                    # Unit tests covering server helpers and agent features

Getting Started

Requirements

• Python 3.11+
• Google Chrome or Chromium (for local automation)
• uv for dependency management (recommended)
• Optional: Claude Desktop or another MCP-compatible client for integration testing

Installation

git clone https://github.com/JovaniPink/mcp-browser-use.git
cd mcp-browser-use
uv sync

Copy sample.env.env to .env (or export the variables another way) and update only the providers you plan to use. Never commit the populated .env file.

Launching the server

uv run mcp-browser-use

The command invokes the console script defined in pyproject.toml, starts the FastMCP application, and registers the run_browser_agent tool.

Using with Claude Desktop

Once the server is running you can register it inside Claude Desktop, for example:

"mcpServers": {
  "mcp_server_browser_use": {
    "command": "uvx",
    "args": ["mcp-browser-use"],
    "env": {
      "MCP_MODEL_PROVIDER": "anthropic",
      "MCP_MODEL_NAME": "claude-3-5-sonnet-20241022"
    }
  }
}

Debugging

For interactive debugging, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/project run mcp-browser-use

The inspector prints a URL that can be opened in the browser to watch tool calls and responses in real time.

Configuration

A full list of environment variables and their defaults is available in documentation/CONFIGURATION.md. Highlights include:

• MCP_MODEL_PROVIDER, MCP_MODEL_NAME, MCP_TEMPERATURE, MCP_MAX_STEPS, MCP_MAX_ACTIONS_PER_STEP, and MCP_USE_VISION control the LLM and agent run.
• Provider-specific API keys and endpoints (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GOOGLE_API_KEY, AZURE_OPENAI_API_KEY, etc.).
• Browser runtime flags (BROWSER_USE_HEADLESS, BROWSER_USE_EXTRA_CHROMIUM_ARGS, CHROME_PERSISTENT_SESSION, BROWSER_USE_PROXY_URL, ...).

Use .env + python-dotenv or your preferred secrets manager to keep credentials out of source control.

Running Tests

uv run python -m pytest -q

The tests cover custom-agent behavior, browser configuration, MCP input limits, secret redaction, and utility helpers. A dependency update is not merge-ready merely because imports or unit tests pass; the resolved environment must also pass its dependency and security checks.

Security

Controlling a full browser instance remotely can grant broad access to the host machine. Review documentation/SECURITY.md before exposing the server to untrusted environments. The complete documentation map and active dependency decision record are in documentation/README.md.

The MCP tool trims and bounds task/context input before allocating a model or browser session. Runtime step limits are constrained, proxy settings are omitted from debug logs, and CDP endpoint values are redacted because they may contain credentials.

The Python 3.14/browser-use dependency migration remains held in #45 until upstream permits patched transitive versions. Do not force incompatible overrides or suppress the audit findings.

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Open a pull request

Bug reports and feature suggestions are welcome—please include logs and reproduction steps when applicable.