chrome-mcp

English | 简体中文

A Model Context Protocol server for browser automation, powered by DrissionPage.

Lets MCP clients (Claude Desktop, Claude Code, Cursor, etc.) drive a real Chromium browser through a minimal 7-tool surface — all sharing one "current tab" pointer.

Why

• Zero learning curve for agents. Facade tools (execute_js, run_cdp, navigate, capture) speak only universal knowledge — JavaScript, the CDP protocol, URLs. No niche-library syntax required for the 90% cases.
• Full power underneath. run_drission_code is the complete-capability base: execute DrissionPage Python code in-process with page / browser / context (persistent dict) / switch_tab() / tabs() / relaunch() injected — loops, waits, multi-tab orchestration, anything one tool call can't express.
• One pointer, always in sync. Switch tabs via DrissionPage code or Target.createTarget/Target.activateTarget CDP commands — every tool follows. (Call tools serially per session; the shared pointer is not concurrency-safe.)
• Multi-instance safe. Per-process isolation (atomic port allocation via socket.bind + PID/UUID private user-data dirs) — spawn N servers, zero conflicts.
• Self-documenting. get_manual returns a compact built-in cheat sheet (DrissionPage locator syntax, error-prone CDP recipes, capture workflow, launch options) — agents fetch it on demand, zero token cost otherwise.

Installation

uv tool install chrome-mcp
# or
uvx chrome-mcp
# or
pip install chrome-mcp

Requires Python ≥ 3.10 and a local Chromium-based browser.

Usage

Add to your MCP client config (e.g. claude_desktop_config.json). Two equivalent forms:

{
  "mcpServers": {
    "chrome": {
      "command": "chrome-mcp"
    }
  }
}

Or run on the fly with uvx (no install needed):

{
  "mcpServers": {
    "chrome": {
      "command": "uvx",
      "args": ["chrome-mcp"]
    }
  }
}

A typical agent flow:

navigate("https://httpbin.org/get")                  → returns tab list
execute_js("return document.body.innerText")         → page data as JSON
capture(action="start", url_filter="api/")
... trigger requests ...
capture(action="get")                                → overview inline,
                                                       full bodies in $TMPDIR/chrome-mcp-captures/*.json

Tools

Launch options

Customize browser startup via command-line args:

{
  "mcpServers": {
    "chrome": {
      "command": "chrome-mcp",
      "args": ["--headless", "--proxy", "http://127.0.0.1:7890", "--arg", "--lang=zh-CN"]
    }
  }
}

Options can also be changed mid-session (destructive, restarts the browser) from inside run_drission_code:

return relaunch(headless=True, user_agent="Mozilla/5.0 ...")

Testing

8 scenario suites run against the real MCP stdio protocol (each spawns an independent server + headless browser — itself a multi-instance concurrency test):

uv run python tests/run_all.py            # full regression
uv run python tests/run_all.py --only smoke,c

Covers: data extraction (DOM tree/pagination/iframes), form interaction (DP actions + CDP input sequences), network capture (filters/timing traps/body fidelity), multi-tab pointer consistency, CDP capabilities (screenshots/emulation/cookies), lifecycle (relaunch/kill-recovery), and real-site scenarios (httpbin/TLS).

License

GPL-3.0-only