browser-use-mcp-server

Use uv to synchronize dependencies and install the necessary Playwright browser binaries:

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

Docker provides an isolated environment. You can run the container with default settings or provide a custom VNC password via a mounted file.

Default run (VNC password: browser-use):

docker build -t browser-use-mcp-server .
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server

Run with 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

The server supports VNC streaming to watch browser automation in real-time. If running via Docker, the VNC port is 5900.

You can use a browser-based viewer like noVNC to connect:

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

Default VNC password: browser-use (unless overridden via Docker secrets).

To run the server using stdio transport, you must first build and install it as a global tool, then run it using the browser-use-mcp-server command. This mode requires mcp-proxy.

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 (JSON):

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

Before installing the server, ensure you have uv, Playwright, and mcp-proxy (required for stdio mode) installed. Use the following commands to set up the environment:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install mcp-proxy and update shell
uv tool install mcp-proxy
uv tool update-shell

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

To run the server using Server-Sent Events (SSE) transport, execute the following command from the source directory:

uv run server --port 8000

To use this in a client (like Cursor or Claude), configure the client with the SSE URL:

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

Create a .env file in your project root to configure the server. The following keys are supported:

• OPENAI_API_KEY: Your OpenAI API key (required).
• CHROME_PATH: (Optional) Path to a specific Chrome installation.
• PATIENT: Set to true if you want API calls to wait for task completion; otherwise, defaults to false.

OPENAI_API_KEY=your-api-key
CHROME_PATH=optional/path/to/chrome
PATIENT=false

Depending on which AI client you are using, the configuration file is located at:

The CLI uses JSON-formatted logging sent to stderr. This is designed for machine-readable logs. The log format includes time, level, name, and message. Errors encountered during server startup are also logged as JSON objects to stderr containing error and traceback fields.

{
  "time": "2025-07-10T12:00:00.000Z",
  "level": "ERROR",
  "name": "browser_use_mcp_server",
  "message": "Error starting server",
  "error": "Some error message",
  "traceback": "Traceback details..."
}