mcp-cdp

mcp-cdp

安全をデフォルトとする Model Context Protocol サーバーです。ピクセル単位の GUI 自動化ではなく、Chrome DevTools Protocol（CDP）を通じて Electron または Chrome/Chromium アプリを操作します。アプリの --remote-debugging-port を指定すると、エージェントは DOM、コンソール、ネットワークリクエスト、実際の入力（クリック／入力／移動）、そして有効化した場合に限り JavaScript の評価を利用できます。

デスクトップ／ウェブアプリでは、コンピューター操作よりも優れている理由：

• スクリーンショットではなく DOM。 エージェントはレンダリング済みの HTML を正確に読み取り、あらゆる要素をクエリできます。より多くの情報を得られ、画面に表示されていない内容も確認できます。
• コンソールとネットワーク。 テストが失敗すると、捕捉されなかった例外や失敗したリクエストをすぐに確認できます。画像から推測する必要はありません。
• 競合なし。 各エージェントは専用のデバッグポートに接続するため、並行して実行するエージェント（たとえば、Git worktree ごとに 1 つ）が同じデスクトップを奪い合うことはありません。
• OS を問わず利用可能。 CDP は macOS、Linux、Windows で同じように動作し、ヘッドレス VPS でも同じ手順を実行できます。

dockndevai MCP サーバースイートの一部であり、すべてのサーバーで共通のガバナンスモデルを採用しています。

エージェントに提供する機能

読み取り専用で起動します（デフォルトで安全を参照）。より高い権限を持つツールは、モードを引き上げた場合にのみ登録されます。

ツール	用途	必要なモード
list_targets	ページ／ウェブビュー／Electron ウィンドウを一覧表示します（ID、種類、タイトル、URL）	読み取り専用
dom_snapshot	ページまたはセレクターのサブツリーのレンダリング済み HTML	読み取り専用
query_dom	CSS セレクターに一致するすべての要素の outer HTML	読み取り専用
console_logs	最近のコンソール出力と捕捉されなかった例外	読み取り専用
network_requests	最近のリクエスト（メソッド、URL、ステータス、MIME。ヘッダーは取得されません）	読み取り専用
screenshot	ビューポートの PNG 画像	読み取り専用
click	セレクターに一致する最初の要素をクリックします	読み書き
type_text	ページにテキストを入力します（先にセレクターにフォーカスします）	読み書き
press_key	Enter／Tab／Escape／Backspace／Delete／矢印キー	読み書き
navigate	確認後に、対象を URL に移動します	読み書き
evaluate	ページ内で JavaScript 式を実行します	管理者 + CDP_ALLOW_EVAL

インストール

npx -y @dockndevai/mcp-cdp

デバッグポートを公開する

アプリ（または worktree の開発ビルド）を、エージェントごとに異なる明示的なポートで起動します。

• Electron アプリ： your-app --remote-debugging-port=9222、またはメインプロセスのコードで app.whenReady() より前に app.commandLine.appendSwitch('remote-debugging-port', '9222') を実行します。
• 通常の Chrome/Chromium： chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/p1 <url>。

起動を確認します：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"
      }
    }
  }
}

Claude Code／Cursor／Codex／VS Code／Windsurf については docs/CLIENTS.md を、すべての変数については .env.example を参照してください。

デフォルトで安全

src/security.ts で強制されます。実際の境界となるのはブラウザプロセスです。これにより、エージェントは意図した対象と操作の範囲内に保たれます。

• CDP_MODE — read-only（デフォルト）→ read-write → admin。設定されたモードより上位のツールは登録されないため、read-only ではエージェントはクリック、入力、ページ移動を一切できません。
• CDP_TARGET_ALLOWLIST — URL が指定したパターンに一致する対象に操作を限定します（空の場合はすべて）。読み取り（調査）は常に許可されます。
• CDP_PROTECTED_TARGETS — 調査はできても、操作はできない対象です。デフォルトでは、サインインページ（accounts.google.com、login.microsoftonline.com、…）とブラウザー内部（chrome://、devtools://、拡張機能）が保護されます。
• CDP_ALLOW_EVAL — evaluate はレンダラー内で任意のコードを実行します。admin モードに加えてこのフラグが必要で、保護された対象では拒否され、人間の確認も必要です。
• CDP_DRY_RUN — 操作の意図をログに記録し、実際には実行せずに戻ります。
• シークレット — リクエスト／レスポンスのヘッダーは一切取得されず（Cookie／認証情報）、機密性の高い URL クエリ値はマスキングされます。また、evaluate と navigate では MCP elicitation を通じて人間に確認を求めます。
• ループバックのみ — CDP_ALLOW_REMOTE=true でない限り、エンドポイントは 127.0.0.1 である必要があります。

オプションの AI リスクガード。 CDP_GUARD_MODE=monitor|enforce を設定すると、evaluate ツールはローカルの laya-guard デーモン（pipx install laya-guard && laya-guard）に問い合わせ、JS 式の実行前に許可／確認／ブロックを判定します。eval のゲートを通過した後に実行され、制限を厳しくすることはできますが、許可を与えることはありません。失敗時は安全側に倒して拒否します。

エージェントにポートの公開方法、スクリーンショットではなく DOM／コンソール／ネットワークの読み取り方法、安全規則、および「なぜ失敗したのか？」を確認するワークフローを教える、同梱スキル cdp-safe-operations があります。SECURITY.md も参照してください。

開発

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

ライセンス

MIT