MCP Browser Use

What You Can Achieve With This MCP

This project aims to empower AI agents to perform web use, browser automation, scraping, and automation with Model Context Protocol (MCP) and Selenium.

The special feature of this MCP is that it can handle multiple agents accessing multiple browser windows. One does not need to start multiple Docker images, VMs, or computers to have multiple scraping agents. And one can still use one single browser profile across all agents. Each agent will have its own windows, and they will not interfere with each other.

This makes the handling of multiple agents seamless: Just start as many agents as you want, and it will just work! Use two Claude Code instances, one Codex CLI instance, one Gemini CLI instance and a fast-agent instance -- all on one computer, all using the same browser profile, and all working (somewhat) in parallel.

Our mission is to let AI agents complete any web task with minimal human supervision -- all based on natural language instructions.

Feature Highlights

HTML Truncation: The MCP allows you to configure truncation of the HTML pages. Other scraping MCPs may overwhelm the AI with accessibility snapshots or HTML dumps that are larger than the context window. This MCP will help you to manage the maximum page size by setting the MCP_MAX_SNAPSHOT_CHARS environment variable.
Multiple Browser Windows and Multiple Agents: You can connect multiple agents to this MCP independently, without requiring coordination on behalf of the agents. Each agent can work with the same browser profile, which is helpful when logins should persist across agents. Each agent gets their own browser window, so they do not interfere with each other. Uses Chrome DevTools Protocol TargetId to identify browser windows.

Known Limitations

Iframe Context: Multi-step interactions within iframes require specifying iframe_selector for each action. Browser context resets after each tool call for reliability. For iframe workflows, repeat the iframe selector parameter in each click_element, fill_text, or debug_element call.

Configuration / Installation

We recommend using Chrome Canary or Chrome Beta. This will ensure that your AI agents will not interfere with your Chrome instance. While this MCP can handle an arbitrary number of agents to use a single Chrome executable, the MCP does require the instance to be started in developer mode. If you, as a normal human user, start your normal Chrome instance manually, the Chrome instance won't be in developer mode. This is a problem. Thus, allow you to use your Chrome browser normally, please just install Chrome Beta (recommended) or Chrome Canary (not recommended due to instability).
After installing Chrome Beta, point to the Chrome Beta executable in the .env file as described below.
Start the MCP server (if you do not know how to do this, check the section "How to Use (This) MCP below).

How to Use (This) MCP

Please refer to the MCP documentation on modelcontextprotocol.io.

Please note that you will need to install all dependencies in the Python environment that your MCP config file points to. For example, if you point to the python or python3 executable, you will point to the global Python environment. Usually it is preferred to point to a virtual environment such as:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

If you have cloned this repository to your local code folder, your MCP config file should look like this:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

and it will be here (in macOS): /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json.

Please refer to the requirements.txt to see which dependencies you need to install.

Restart Claude to see if the JSON config is valid. Claude will lead to you the error logs for the MCP if something is off.

If the setup was successful, you will see a small hammer icon in the bottom-right of the "New Chat" window in Claude. Next to the hammer will be the number of functions that the MCP provides.

Click the hammer to see the available tools.

Environment Variable Configuration

IMPORTANT: Define all environment variables in your project root .mcp.json file, NOT in .env files. This ensures a single source of truth with no conflicts.

Recommended Configuration (Chrome Beta)

Add environment variables to the env section of your .mcp.json file:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Windows Example:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

Environment Variable Reference

Variable	Description	Example
`BETA_PROFILE_NAME`	Name of Chrome profile to use	`"SeleniumProfile"`
`BETA_EXECUTABLE_PATH`	Path to Chrome Beta executable	See examples above
`BETA_PROFILE_USER_DATA_DIR`	Chrome Beta user data directory	See examples above
`CHROME_REMOTE_DEBUG_PORT`	Port for Chrome remote debugging	`"9225"`
`MCP_HEADLESS`	Run in headless mode (0=no, 1=yes)	`"0"`
`MCP_ENABLE_EXTENSIONS`	Enable Chrome extensions (0=no, 1=yes)	`"1"`
`MAX_SNAPSHOT_CHARS`	Maximum HTML snapshot size	`"10000"`

Why Use Chrome Beta?

Using Chrome Beta (or Canary) prevents conflicts with your regular Chrome browser:

AI agents require Chrome to run with remote debugging enabled
Your normal Chrome instance cannot run with remote debugging
Chrome Beta allows both to coexist on the same system

Profile Recommendations

Use a dedicated profile like "SeleniumProfile" (NOT "Default")
This prevents conflicts if you open Chrome Beta manually
Extensions and logins persist in this profile across sessions
Each AI agent gets its own browser window but shares the profile

Available Tools

Debugging

Check if the browser is running by visiting this URL in your main browser (not the automated browser):

http://127.0.0.1:9223/json/version

It will display something like this if the browser is running:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

Lock Files and Coordination

This MCP uses file-based locking to coordinate multiple agents accessing the same browser profile. All lock files are stored in tmp/mcp_locks/ in the project root directory for easy inspection.

Lock File Types

Action Lock (<hash>.softlock.json and <hash>.softlock.mutex)

Ensures only one agent can perform browser actions at a time
Default TTL: 30 seconds (configurable via MCP_ACTION_LOCK_TTL)
Automatically renewed with heartbeat while agent is working
Agents wait up to 60 seconds to acquire lock (configurable via MCP_ACTION_LOCK_WAIT)

Window Registry (<hash>.window_registry.json)

Tracks which agent owns which browser window
Contains: targetId, windowId, process PID, last heartbeat timestamp
Used for orphan cleanup: automatically closes windows from crashed/stale agents
Stale threshold: 5 minutes (configurable via MCP_WINDOW_REGISTRY_STALE_SECS)

Startup Mutex (<hash>.startup.mutex)

Ensures single browser instance startup per profile
Used during initial Chrome process launch coordination

File Format: The <hash> is a SHA-256 hash derived from your Chrome profile's user_data_dir and profile_name, ensuring stable identification across processes.

Configuration

You can customize lock behavior with these environment variables:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

Orphan Window Cleanup

When an agent starts a browser session, it automatically:

Checks the window registry for entries from dead processes (PID no longer exists)
Checks for stale entries (no heartbeat for >5 minutes)
Closes orphaned windows via Chrome DevTools Protocol
Cleans up registry entries

This ensures crashed or terminated agents don't leave zombie browser windows open.

Demo Video (YouTube)

Run Tests

We DO NOT want to use pytest-asyncio.

pip install -e ".[test]"`

浏览器使用