JovaniPink/mcp-browser-use

> 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
bash
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
bash
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:
json
"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