cdp-browser-mcp

MCP server that attaches to an already-running Chromium browser over the Chrome DevTools Protocol (CDP). It does not launch a browser. One process can hold many sessions, so an agent can drive several profiles at once.

Works with:

• Chrome / Edge started with --remote-debugging-port=9222

• Fingerprint browsers (AdsPower, BitBrowser, GoLogin, Multilogin, …)

• Cloud or local CDP endpoints (http://127.0.0.1:9222, ws://…)

Uses Patchright (connectOverCDP) so the attached context is less likely to be patched by anti-bot checks than stock Playwright.

Install from GitHub (no npm publish). Requires Node.js 18+. No Chromium download is needed.

npx -y github:killaragorn/cdp-browser-mcp

Cursor

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "cdp-browser-mcp": {
      "command": "npx",
      "args": ["-y", "github:killaragorn/cdp-browser-mcp"]
    }
  }
}

Related MCP server: Ghostlight

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cdp-browser-mcp": {
      "command": "npx",
      "args": ["-y", "github:killaragorn/cdp-browser-mcp"]
    }
  }
}

Claude Code

claude mcp add --scope user cdp-browser-mcp -- npx -y github:killaragorn/cdp-browser-mcp

Or commit .mcp.json in a project so teammates get the same server:

{
  "mcpServers": {
    "cdp-browser-mcp": {
      "command": "npx",
      "args": ["-y", "github:killaragorn/cdp-browser-mcp"]
    }
  }
}

Codex

codex mcp add cdp-browser-mcp -- npx -y github:killaragorn/cdp-browser-mcp

Or add to ~/.codex/config.toml:

[mcp_servers.cdp-browser-mcp]
command = "npx"
args = ["-y", "github:killaragorn/cdp-browser-mcp"]

Local clone

git clone https://github.com/killaragorn/cdp-browser-mcp.git
cd cdp-browser-mcp
npm install

Then point the client at node /absolute/path/to/cdp-browser-mcp/index.mjs.

Typical flow

1. Start a browser with CDP, for example:

chrome --remote-debugging-port=9222

Or copy the debug URL from AdsPower / BitBrowser (often http://127.0.0.1:xxxx).

2. Ask the agent to connect, then operate the page:

• cdp_connect → { "cdp_url": "http://127.0.0.1:9222", "capture_dir": "D:/captures/run1" }

• or cdp_network_start with dir after connect

• Each request is saved as {dir}/000001_GET_host-path.json plus requests.jsonl

• cdp_close when finished

Tools

Connect first with cdp_connect. Network capture stays off unless you pass capture_dir or call cdp_network_start.

Session / navigation

Input

Network

Capture is off by default. Pass capture_dir on connect, or call cdp_network_start. Every matching request is written to disk with no count limit. xhr/fetch/document/JSON response bodies are stored in full.

{capture_dir}/
  capture.json
  requests.jsonl
  000001_GET_example.com-.json
  000002_POST_api.example.com-login.json

Cookies

Why this exists

@playwright/mcp launches (or binds) a single browser from CLI flags. This server is the opposite shape:

• Connect is a tool, not a startup flag — the agent picks the CDP URL at runtime

• Many sessions in one MCP process (one AdsPower profile per session_id)

• Patchright instead of Playwright, aimed at already-fingerprinted browsers

License

MIT