chromium-cdp-mcp

Model Context Protocol server that lets an AI assistant drive any Chromium-based browser via the Chrome DevTools Protocol. No Puppeteer, no Playwright — a thin layer of native WebSocket directly to the browser's --remote-debugging-port.

What it is

A standalone MCP server (TypeScript). Once an MCP-aware client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue.dev, Zed, Codex CLI, Goose, …) loads it, the AI can:

• navigate, click, fill, scroll, type, select options, take screenshots
• run arbitrary JavaScript and receive the real return value
• handle JS dialogs (alert / confirm / prompt / beforeunload)
• click inside cross-origin iframes (Cloudflare Turnstile, reCAPTCHA, embed widgets)
• manage tabs, override the viewport, send raw CDP commands

The server is browser-agnostic: every tool takes a port argument and connects to whatever Chromium-based browser is listening on that port.

What it is NOT

• Not a profile / fingerprint manager. For antidetect profile creation, proxies, cookies, and batched profile orchestration use a separate MCP such as undetectable-local-api-mcp-ts.
• Not a browser launcher. You start the browser yourself (or via the antidetect software); this server attaches.

Install

From npm

# in your MCP client config — auto-fetches and runs
npx -y chromium-cdp-mcp

From source

git clone https://github.com/<your-org>/chromium-cdp-mcp
cd chromium-cdp-mcp
npm install
npm run build
node dist/server.js     # or `npm start`

Requires Node.js ≥ 22 (native WebSocket).

MCP client config

Same shape for every client. Example (claude_desktop_config.json etc.):

{
  "mcpServers": {
    "chromium-cdp": {
      "command": "npx",
      "args": ["-y", "chromium-cdp-mcp"]
    }
  }
}

For a local checkout:

{
  "mcpServers": {
    "chromium-cdp": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-CDP/dist/server.js"]
    }
  }
}

Launch a browser with CDP enabled

The server connects to an already-running Chromium instance via its remote debugging port. Start one of these first:

Chrome / Chromium

# Linux / macOS
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-cdp

# Windows (PowerShell or cmd)
"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="%TEMP%\chrome-cdp"

Microsoft Edge

"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="%TEMP%\edge-cdp"

Brave / Opera / Vivaldi / Yandex Browser

Same --remote-debugging-port=PORT flag — every Chromium fork supports it.

Puppeteer / Playwright launchers

// Puppeteer
const browser = await puppeteer.launch({
  args: ["--remote-debugging-port=9222"],
});

// Playwright (chromium)
const browser = await chromium.launch({
  args: ["--remote-debugging-port=9222"],
});

Use a fresh profile

--user-data-dir points to a clean profile directory. Without it, Chrome refuses to enable remote debugging on your default profile (a 122+ security restriction).

Verify the port is live

curl http://127.0.0.1:9222/json/version

If you see JSON with webSocketDebuggerUrl, you're ready.

Connection block

Every tool accepts the same connection fields:

| Field | Type | Description | | -------------- | -------- | ---------------------------------------------------------------------------- | | port | number | The browser's --remote-debugging-port. Required. | | host | string | Default 127.0.0.1. | | target_id | string | Explicit page targetId from list_tabs. Skips auto-pick. | | url_contains | string | Pick the first page whose URL contains this substring. | | tab_index | number | Pick page by index in Target.getTargets order. |

Auto-pick (when none of target_id / url_contains / tab_index is given): the first attached page, falling back to the first page in the target list.

Tools

Connection / tabs

| Tool | What it does | | ----------- | --------------------------------------------------------------------- | | connect | Probe /json/version + /json/list. Diagnostic. | | list_tabs | Target.getTargets. Returns {targetId, type, url, title, attached}.| | new_tab | Open a new tab. Optional url. Returns the new targetId. | | close_tab | Close the tab specified by target_id. |

Navigation

| Tool | What it does | | ---------- | ---------------------------------------------------------------------------- | | navigate | Page.navigate + best-effort wait for load. Returns final URL. | | back | history.back(). | | forward | history.forward(). | | reload | Page.reload, optional ignore_cache. |

JavaScript

| Tool | What it does | | --------------- | ------------------------------------------------------------------------------------------------------- | | evaluate | Runtime.evaluate with awaitPromise=true, returnByValue=true. Returns the actual value. | | get_page_html | document.documentElement.outerHTML. | | get_url | location.href. |

DOM interactions

| Tool | What it does | | -------------------------- | ----------------------------------------------------------------------------------------------- | | click | Real mouse press+release at the element's center. CSS or XPath selector. | | click_at | Real mouse press+release at raw viewport (x, y). | | click_iframe | Real click inside any iframe (cross-origin friendly). dx / dy offsets, default center. | | click_and_accept_dialog | Click AND auto-handle any alert / confirm / prompt dialog the click triggers. | | handle_dialog | Handle a currently-open JS dialog. accept, optional prompt_text. | | fill | Focus + Input.insertText. Clears existing value unless append=true. Supports unicode. | | select_option | Set <select> value + dispatch input and change events so frameworks react. | | focus | el.focus(). | | scroll_to | Scroll element into view (center). Returns its bounding rect. | | scroll | window.scrollTo(x,y) (absolute) or scrollBy(dx,dy) (relative). | | press_key | Input.dispatchKeyEvent — Enter / Tab / Escape / arrows / printable chars / unicode. | | wait_for | Poll for a selector until it appears (or timeout). |

Capture / emulation

| Tool | What it does | | -------------- | -------------------------------------------------------------------------------------------------- | | screenshot | Page.captureScreenshot → file. full_page, format (png / jpeg), quality. | | set_viewport | Emulation.setDeviceMetricsOverride. Mobile emulation. clear: true to reset. |

Escape hatch

| Tool | What it does | | ----- | -------------------------------------------------------------------------------------------------- | | raw | Send any CDP method directly. For things not exposed as a dedicated tool: Network.*, Storage.*, Fetch.*, Target.activateTarget, etc. |

Selectors

Any selector starting with / or (/ is treated as XPath. Everything else is treated as CSS. Examples:

input[name="email"]                    # CSS
#submit                                # CSS
//button[contains(.,"Войти")]          # XPath
(//a[@class="title"])[3]               # XPath

Quickstart for an AI assistant

A natural step sequence for filling and submitting a form looks like this:

1. connect            { port: 9222 }                                # confirm browser is alive
2. navigate           { port: 9222, url: "https://example.com" }    # load page
3. wait_for           { port: 9222, selector: "input#email" }       # wait for hydration
4. fill               { port: 9222, selector: "input#email", text: "[email protected]" }
5. fill               { port: 9222, selector: "input#password", text: "<entered by user>" }
6. click_and_accept_dialog
                      { port: 9222, selector: "#submit", accept: true }
7. wait_for           { port: 9222, selector: ".dashboard" }
8. screenshot         { port: 9222, path: "/tmp/dashboard.png" }

Integration with antidetect browsers

Antidetect / multi-profile browsers expose a remote-debugging port per running profile. Hand that port to this MCP and it can drive the underlying browser without caring about fingerprinting, proxies, or profile state — those are managed by the antidetect's own MCP / API.

Example: Undetectable + chromium-cdp-mcp

Undetectable's local API (and its undetectable-local-api-mcp-ts wrapper) returns a debug_port whenever a profile is started:

// undetectable-local-api-mcp-ts → start_profile response
{
  "code": 0,
  "data": {
    "debug_port": "52967",
    "websocket_link": "ws://127.0.0.1:52967/devtools/browser/<id>",
    "name": "my-profile"
  },
  "status": "success"
}

Feed 52967 straight into this MCP's tools:

// chromium-cdp-mcp → navigate
{ "port": 52967, "url": "https://example.com" }

This split keeps responsibilities clean:

• undetectable-local-api-mcp-ts — create profile, set proxy, set OS/browser, start / stop, batch operations, cookies, fingerprint configs.
• chromium-cdp-mcp — everything the AI does inside the browser session.

The same pattern works for any antidetect browser or headless launcher that publishes a webSocketDebuggerUrl on a known port (AdsPower, GoLogin, Multilogin, Puppeteer, Playwright …).

Env

| Variable | Default | Notes | | ------------- | ------- | ------------------------------------------------ | | CDP_TIMEOUT | 30 | Per-command timeout in seconds. |

Known limitations

• Native WebSocket required. Node ≥ 22.
• Cross-origin iframe selectors. click / fill / select_option use a selector evaluated against the main page DOM. For elements inside a cross-origin iframe (Cloudflare Turnstile, reCAPTCHA, embedded YouTube …) use click_iframe (selector resolves to the iframe element, the click lands inside) or click_at with raw coordinates.
• Dialog handling. Native alert / confirm / prompt block page JS until handled. Use click_and_accept_dialog to do both in one call, or handle_dialog to dismiss an already-open one.
• Ephemeral session. Each tool call opens a fresh WebSocket and closes it on return. That keeps the server stateless but means CDP event subscriptions are scoped to a single call (this is fine for the supplied tools — the dialog tool handles its own subscription internally).

⚠️ AI gets full browser control. Once connected, an AI client can drive any tab on the target browser: navigate, click, fill forms, run JS, read page content, take screenshots. Only point this server at browsers you are willing to give the AI full access to. Review tool calls in your MCP client.

License

MIT