MCP Browser Use

<br>
<br>
<br>

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.

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

brew install --cask google-chrome-beta

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -

echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \

    | sudo tee /etc/apt/sources.list.d/google-chrome.list

sudo apt update && sudo apt install -y google-chrome-beta

google-chrome-beta --version      # Linux

or


"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

sudo apt install -y xvfb
Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &
Tell Chrome which display to use
export DISPLAY=:99

After installing Chrome Beta, point to the Chrome Beta executable in your .mcp.json as described in the Environment Variable Configuration section 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):

```