MCP Browser Use Server

How to use

To use this MCP server, you run it as a local stdio MCP host and connect your MCP client to it. The server coordinates multiple agents, giving each agent its own browser window while sharing the same profile. You install dependencies, start the local MCP process, and then configure your client to load the server via the provided command and environment setup.

How to install

Prerequisites: you need Python installed in a virtual environment for running the MCP server. You also need Chrome Beta (or Canary) installed to avoid conflicts with your regular Chrome.

# Example Python virtual environment setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create or use a Python virtual environment and prepare the MCP server as shown in the configuration example. Then start Claude or your MCP client to load the server configuration.

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

Configuration and environment setup

Define all environment variables in your project root configuration file under the MCP settings. Do not place them in other env files to keep a single source of truth.

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": [
        "/path/to/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"
      }
    }
  }
}

Environment variable reference

The most common environment variables control the Chrome profile, executable, debugging port, and rendering limits. Use the values shown or adapt them to your system.

{
  "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"
}

Debugging

Verify the browser is running by checking the remote debugging endpoint from a regular browser. You should see the expected JSON with the WebSocket URL for DevTools when the browser is active.

Locking, coordination, and cleanup

This MCP coordinates access to the shared browser profile using file-based locks. It keeps a window registry to map each agent to a browser window and cleans up stale or orphaned windows when agents crash or terminate unexpectedly.

Run tests

To run tests, install the test extras and avoid pytest-asyncio as part of the setup.

pip install -e ".[test]"