Browser Use MCP server for AI agents

The browser-use MCP server enables AI agents to control web browsers through a Model Context Protocol interface. It integrates with browser-use to provide a powerful way for AI systems to interact with web content.

Prerequisites

Before installing the MCP server, ensure you have the following components:

uv: A fast Python package manager
Playwright: For browser automation
mcp-proxy: Required if using stdio mode

Install these prerequisites with:

# Install prerequisites
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install mcp-proxy
uv tool update-shell

Environment Setup

Create a .env file in your project directory with the following contents:

OPENAI_API_KEY=your-api-key
CHROME_PATH=optional/path/to/chrome
PATIENT=false  # Set to true if API calls should wait for task completion

Installation

Install the server and its dependencies:

# Install dependencies
uv sync
uv pip install playwright
uv run playwright install --with-deps --no-shell chromium

Running the Server

SSE Mode

This is the simplest way to run the server:

# Run directly from source
uv run server --port 8000

stdio Mode

For stdio transport, you'll need to build and install the package:

# 1. Build and install globally
uv build
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
uv tool install dist/browser_use_mcp_server-*.whl

# 2. Run with stdio transport
browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

Client Configuration

SSE Mode Configuration

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio Mode Configuration

{
  "mcpServers": {
    "browser-server": {
      "command": "browser-use-mcp-server",
      "args": [
        "run",
        "server",
        "--port",
        "8000",
        "--stdio",
        "--proxy-port",
        "9000"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Where to Place Configuration Files

Depending on your client, place the configuration in the following locations:

Client	Configuration Path
Cursor	`./.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Claude (Mac)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`

Using Docker

Docker provides an isolated environment for running the server:

# Build the Docker image
docker build -t browser-use-mcp-server .

# Run the container with the default VNC password ("browser-use")
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server

# Run with a custom VNC password
echo "your-secure-password" > vnc_password.txt
docker run --rm -p8000:8000 -p5900:5900 \
  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
  browser-use-mcp-server

Using the VNC Viewer

You can view browser automation in real-time using VNC:

# Browser-based viewer
git clone https://github.com/novnc/noVNC
cd noVNC
./utils/novnc_proxy --vnc localhost:5900

Default VNC password: browser-use (unless you specified a custom password)

Example Usage

Try asking your AI assistant:

open https://news.ycombinator.com and return the top ranked article

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "browser-use-mcp-server" '{"url":"http://localhost:8000/sse"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "browser-use-mcp-server": {
            "url": "http://localhost:8000/sse"
        },
        "browser-server": {
            "command": "browser-use-mcp-server",
            "args": [
                "run",
                "server",
                "--port",
                "8000",
                "--stdio",
                "--proxy-port",
                "9000"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "browser-use-mcp-server": {
            "url": "http://localhost:8000/sse"
        },
        "browser-server": {
            "command": "browser-use-mcp-server",
            "args": [
                "run",
                "server",
                "--port",
                "8000",
                "--stdio",
                "--proxy-port",
                "9000"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect