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 –
CustomAgentwrapsbrowser-use's base agent to add history export, richer prompts, and consistent error handling across runs. - Centralised browser configuration –
create_browser_sessiontranslates environment variables into a ready-to-useBrowserSession, enabling persistent profiles, proxies, and custom Chromium flags without touching the agent logic. - FastMCP integration –
server.pyregisters the MCP tool, normalises configuration, and ensures the browser session is always cleaned up. - Client helpers –
client.pyincludes 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)
uvfor 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, andMCP_USE_VISIONcontrol 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.