Mcp Cdp

io.github.dockndevaiPublished by GitHub account dockndevaiv0.2.3Updated Oct 26, 2026

Safe-by-default MCP that drives an Electron/Chrome app over CDP: DOM, console, network, input.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

Safe-by-default MCP server that drives an Electron or Chrome/Chromium app over the Chrome DevTools Protocol, exposing DOM, console, network and input tools.

What you can do
  • List debuggable targets such as pages, webviews and Electron windows, with id, type, title and URL.
  • Read rendered HTML of a whole page or a CSS selector's subtree, and query the outer HTML of matching elements.
  • Inspect recent console output, uncaught exceptions and network requests (method, URL, status, MIME, failures).
  • Capture a PNG screenshot of the viewport for layout and rendering checks.
  • In read-write mode, click elements, type text, press keys and navigate a target to a URL.
  • In admin mode with an explicit flag, evaluate JavaScript expressions in the page.
When to use it
Useful when an assistant needs to inspect or drive a desktop or web app that exposes a DevTools port, for example debugging a failing UI test, reading exact DOM instead of screenshots, or checking console errors and failed requests. Also suits parallel agents that each attach to their own debugging port.
Requirements
Runs locally via npx from the npm package; Node.js needed. The target app or browser must be started with a remote debugging port (CDP_PORT, default 9222) on a loopback host (CDP_HOST). CDP_MODE selects read-only, read-write or admin; CDP_ALLOW_EVAL is needed for the evaluate tool. No accounts or API keys declared.
Before you install
Starts read-only, but raising CDP_MODE to read-write lets the assistant click, type and navigate in the app, and admin plus CDP_ALLOW_EVAL allows arbitrary JavaScript execution in the renderer. Use CDP_TARGET_ALLOWLIST and protected targets to limit scope, and CDP_DRY_RUN to log interactions without dispatching. Headers are not captured and sensitive URL query values are redacted, but page content and network metadata are sent to the model.

Installation

In SourceWeft

  1. Open Mcp Cdp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-cdp

[npm] [CI] [licence]

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.

ToolForNeeds mode
list_targetslist pages / webviews / Electron windows (id, type, title, url)read-only
dom_snapshotrendered HTML of the page or a selector's subtreeread-only
query_domouter HTML of every element matching a CSS selectorread-only
console_logsrecent console output + uncaught exceptionsread-only
network_requestsrecent requests (method, url, status, mime; headers never captured)read-only
screenshota PNG of the viewportread-only
clickclick the first element matching a selectorread-write
type_texttype into the page (focus a selector first)read-write
press_keyEnter / Tab / Escape / Backspace / Delete / Arrowsread-write
navigatenavigate a target to a URL (confirmed)read-write
evaluaterun a JavaScript expression in the pageadmin + CDP_ALLOW_EVAL

Install

bash
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.

Configure

json
{  "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

bash
npm installnpm run build# list the tools:echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | CDP_PORT=9222 node dist/index.jsnpm test

Licence

MIT

Source: README.md at commit a533f1b

Tools

6

list_targets

List targets

List the debuggable targets on the DevTools endpoint — pages, webviews and Electron windows — with their id, type, title and URL. Start here to find the target id every other tool needs.

Takes no parameters.

dom_snapshot

DOM snapshot

Return the rendered HTML of a target — the whole document, or just the subtree of the first element matching a CSS selector. This is the DOM the agent should read instead of a screenshot: it carries far more information and is exact.

Parametersselectortarget_idrequired

query_dom

Query DOM

Return the outer HTML of every element matching a CSS selector (capped). Use to locate the exact elements to click or type into, and to confirm what is actually on the page.

Parameterslimitselectorrequiredtarget_idrequired

console_logs

Console logs

Return recent console output and uncaught exceptions captured from the target since it was first inspected. The fastest way to see why something failed — errors that never appear on screen.

Parameterslimittarget_idrequired

network_requests

Network requests

Return recent network requests captured from the target — method, URL, status, MIME type, failures. Headers are never captured and sensitive URL query values are redacted.

Parameterslimittarget_idrequiredurl_filter

screenshot

Screenshot

Capture a PNG screenshot of the target's viewport. Prefer dom_snapshot for reading content; use this for visual layout, rendering and image checks.

Parameterstarget_idrequired

Version history

3
  1. v0.2.3LatestOct 26, 2026
  2. v0.2.0Sep 27, 2026
  3. v0.1.0Sep 22, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts