browser-mcp-server

Full browser control for any LLM agent via the Model Context Protocol (MCP).

Powered by browser-use — a persistent, Playwright-backed browser session that your agent controls step-by-step.

✨ Key Feature: Zero State Calls

Every action that changes the page (open, click, input, type, keys, scroll, back) automatically returns the updated page state in the same response. Your agent never wastes a round-trip calling state after an action — it's already there.

Installation

pip install browser-mcp-server

Chromium is installed automatically on first run. The server detects whether the browser binary is present and downloads it if not (~170 MB, one-time). You never need to run playwright install chromium manually.

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "browser-use": {
      "command": "browser-mcp-server"
    }
  }
}

Cursor / Zed / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "browser-use": {
      "command": "browser-mcp-server"
    }
  }
}

nixagent (mcp.json)

{
  "mcpServers": {
    "browser-use": {
      "command": "browser-mcp-server",
      "active": true
    }
  }
}

from nixagent import Agent

agent = Agent(
    name="BrowserAgent",
    system_prompt="You are a web browsing assistant.",
    mcp_config_path="mcp.json"
)
agent.run("Go to stripe.com and tell me the pricing for the Starter plan.")

HTTP / Remote Agents

# Modern streaming (recommended)
browser-mcp-server --transport streamable-http --port 8080

# Legacy SSE
browser-mcp-server --transport sse --port 8080

Available Tools

How the Auto-State Works

Traditional browser agents need two calls to interact:

1. agent calls: state         → get element indexes
2. agent calls: click 3       → click
3. agent calls: state         → get updated indexes  ← wasted call
4. agent calls: input 7 "..." → type

With browser-mcp-server, every mutating action returns fresh state in its own response:

1. agent calls: open https://...  → navigated + state returned ✓
2. agent calls: click 3           → clicked + updated state returned ✓
3. agent calls: input 7 "..."     → typed + updated state returned ✓

CLI Reference

usage: browser-mcp-server [-h] [--transport {stdio,sse,streamable-http}]
                        [--host HOST] [--port PORT]

options:
  --transport   stdio | sse | streamable-http  (default: stdio)
  --host        host for HTTP transports       (default: 127.0.0.1)
  --port        port for HTTP transports       (default: 8080)

Requirements

• Python 3.10+
• browser-use >= 0.12.0
• mcp >= 1.0.0
• Chromium (installed via playwright install chromium)

License

MIT