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 production-ready 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 back to the client. The refactored layout focuses on keeping configuration in one place, improving testability, and keeping browser-use upgrades isolated from MCP specific code.

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
├── .env.example            # 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 to .env (or export the variables in another way) and update the values for the providers you plan to use.

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 pytest

The tests cover the custom agent behaviour, browser session factory, and other utility helpers.

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.

Contributing

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

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