mcp-cdp
A safe-by-default Model Context Protocol server that drives an Electron or Chrome/Chromium app over the Chrome DevTools Protocol (CDP) — instead of pixel-level GUI automation. Point it at the app's --remote-debugging-port and an agent gets the DOM, console, network requests, real input (click / type / navigate), and — gated — JavaScript evaluation.
Why this beats computer-use for a desktop/web app:
- The DOM, not a screenshot. The agent reads exact rendered HTML and can query any element — far more information, and it sees things that aren't on screen.
- Console + network. When a test fails, the uncaught exception or the failed request is right there — no guessing from an image.
- No collisions. Each agent attaches to its own debugging port, so parallel agents (e.g. one per git worktree) never fight over one desktop.
- Cross-OS. CDP works identically on macOS, Linux and Windows — the same flow runs on a headless VPS.
Part of the dockndevai MCP server suite — one governance model across all of them.
What it gives an agent
Starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.
| Tool | For | Needs mode |
|---|
list_targets | list pages / webviews / Electron windows (id, type, title, url) | read-only |
dom_snapshot | rendered HTML of the page or a selector's subtree | read-only |
query_dom | outer HTML of every element matching a CSS selector | read-only |
console_logs | recent console output + uncaught exceptions | read-only |
network_requests | recent requests (method, url, status, mime; headers never captured) | read-only |
screenshot | a PNG of the viewport | read-only |
click | click the first element matching a selector | read-write |
type_text | type into the page (focus a selector first) | read-write |
press_key | Enter / Tab / Escape / Backspace / Delete / Arrows | read-write |
navigate | navigate a target to a URL (confirmed) | read-write |
evaluate | run a JavaScript expression in the page | admin + CDP_ALLOW_EVAL |
Install
npx -y @dockndevai/mcp-cdp
Expose a debugging port
Start your app (or a worktree's dev build) with an explicit port — one per agent:
- Electron app:
your-app --remote-debugging-port=9222, or in main-process code
app.commandLine.appendSwitch('remote-debugging-port', '9222') before app.whenReady().
- Plain Chrome/Chromium:
chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/p1 <url>.
Check it's up: curl http://127.0.0.1:9222/json/version.
{
"mcpServers": {
"cdp": {
"command": "npx",
"args": ["-y", "@dockndevai/mcp-cdp"],
"env": {
"CDP_PORT": "9222",
"CDP_MODE": "read-only"
}
}
}
}
See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf, and .env.example for every variable.
Safe by default
Enforced by src/security.ts. The browser process is the real boundary — this keeps an agent inside the targets and actions you intend:
CDP_MODE — read-only (default) → read-write → admin. Tools above the mode aren't registered, so in read-only the agent cannot click, type or navigate at all.CDP_TARGET_ALLOWLIST — confine interactions to targets whose URL matches your patterns (empty = all). Reads (inspection) are always allowed.CDP_PROTECTED_TARGETS — targets that can be inspected but never interacted with. Defaults protect sign-in pages (accounts.google.com, login.microsoftonline.com, …) and browser internals (chrome://, devtools://, extensions).CDP_ALLOW_EVAL — evaluate is arbitrary code execution in the renderer: admin mode plus this flag, refused on protected targets, with a human confirmation.CDP_DRY_RUN — interactions log their intent and return without dispatching.- Secrets — request/response headers are never captured (cookies/auth), and sensitive URL query values are redacted.
evaluate and navigate also prompt a human via MCP elicitation.
- Loopback only — the endpoint must be
127.0.0.1 unless CDP_ALLOW_REMOTE=true.
Optional AI risk guard. Set CDP_GUARD_MODE=monitor|enforce to have the evaluate tool consult a local laya-guard daemon (pipx install laya-guard && laya-guard) that classifies the JS expression allow/confirm/block before it runs. It runs after the eval gate and can only tighten, never grant; fails closed.
There is a bundled skill, cdp-safe-operations, that teaches an agent how to expose a port, read the DOM/console/network instead of screenshots, the safety rules, and the "why did this fail?" workflow. See also SECURITY.md.
Developing
npm install
npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | CDP_PORT=9222 node dist/index.js
npm test
Licence
MIT