chrome-debugger-mcp

日本語 | 中文

日本語

ブレークポイント駆動の Chrome デバッグのための MCP サーバー。

chrome-debugger-mcp は Chrome DevTools Protocol のプリミティブを MCP ツールとして公開し、AI エージェントが実際の Chrome タブにアタッチし、実行を一時停止し、スコープ値を検査し、現在のコールフレーム内で式を評価し、静的ソースから推測するのではなくランタイムの事実に基づいてコードをステップ実行できるようにします。

これは汎用のブラウザ自動化サーバーではありません。焦点はランタイムデバッグです。

コア機能

• ユーザーの明示的な確認後に CDP 経由で実際の Chrome タブにアタッチする

• ブレークポイントまたは debugger; ステートメントで一時停止し、期待する正確な一時停止を待つ

• 一時停止したフレームからローカル、クロージャ、モジュールスコープの値を読み取る

• 現在のコールフレームで JavaScript を評価し、実行を前方にステップ実行する

• クリーンに再開し、エージェントが実際のランタイム値で続行できるようにする

デモ

デモ: エージェントが Chrome を起動し、ブレークポイントを待ち、実際のスコープ変数を検査し、推測ではなくランタイムの事実に基づいて再開します。

MCP クライアント設定

公開済みパッケージを使用する

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

インストール

npm から

npx -y chrome-debugger-mcp

またはグローバルにインストール:

npm install -g chrome-debugger-mcp

ソースから

pnpm install
pnpm build
node dist/index.js

その他の特長

• リモートデバッグを有効にした専用の Chrome インスタンスを起動する

• ソースコードを編集せずに DevTools ブレークポイントを設定・削除する

• CDP 経由でページをリロードし、ナビゲーション後にブレークポイントが確実にバインドされるようにする

• MCP クライアントのリクエストタイムアウトが短い場合にデバッガーの状態をポーリングする

• クライアントがユーザーに表示できる _ui ペイロードとログメッセージを出力する

なぜ役立つのか

多くのブラウザ特化型 MCP ツールは DOM 操作とネットワーク検査に強いですが、ランタイムデバッグには弱いです。このサーバーは、通常 Chrome DevTools で使用する欠けているループを MCP クライアントに提供します: 正しいタブにアタッチし、適切なタイミングで一時停止し、実際の値を検査し、必要に応じてステップ実行し、クリーンに再開します。

また、エージェントのよくあるミスを防ぐガードレールも追加します:

• どのタブにアタッチするかを推測する

• ランタイム値を検査せずに挙動を結論づける

• reloadPage() と waitForSpecificPause() の間でターンを終了する

要件

• ローカルに Google Chrome がインストールされていること

• stdio サーバーとツール呼び出しをサポートする MCP クライアント

• デバッグしたいアプリケーションへのアクセス

• 一時的な debugger; ステートメントを挿入する場合はローカルソースへのアクセス

ツールモデル

サーバーは stdio 経由で実行され、MCP ツールを公開します。最も重要なツールは次のとおりです:

• startDebuggingSession: 推奨されるデバッグワークフローとエージェントの行動に関する重要なルールを返します

• launchChrome: リモートデバッグを有効にした専用の Chrome インスタンスを起動します

• listTargets: 利用可能な Chrome タブを一覧表示し、ユーザーに選択を求めます

• connect: 確認されたタブにアタッチします

• setBreakpoint: ソースファイルを変更せずに CDP ブレークポイントを作成します

• removeBreakpoint: setBreakpoint で作成されたブレークポイントを削除します

• reloadPage: CDP 経由で現在のページをリロードします

• waitForSpecificPause: 次の一時停止を待ち、ターゲットのファイルと行に一致するかどうかを確認します

• waitForPause: 位置の一致なしに任意の一時停止を待ちます

• getScopeVariables: 一時停止したフレームからローカル、クロージャ、モジュールスコープの値を読み取ります

• evaluate: 一時停止したコールフレームで JavaScript を実行します

• stepInto、stepOver、stepOut: 標準の実行制御

• resume: 検査後に実行を再開します

• getStatus: 接続状態または一時停止状態の非ブロッキングポーリング

• forcePause: 次の JavaScript ステートメントでの一時停止を要求します

推奨ワークフロー

AI クライアント向けの推奨フローは次のとおりです:

1. startDebuggingSession() を呼び出します。

2. launchChrome() を呼び出すか、CDP ポートが開いている既存の Chrome インスタンスを使用します。

3. listTargets() を呼び出し、完全なタブリストをユーザーに表示します。

4. ユーザーが正確なページ URL を確認するのを待ちます。

5. connect({ targetUrl }) を呼び出します。

6. ローカルソースコードに一時的な debugger; ステートメントを挿入するか、setBreakpoint() を呼び出します。

7. reloadPage() を呼び出します。

8. 同じターン内で直ちに waitForSpecificPause() を呼び出します。

9. getScopeVariables() と evaluate() を呼び出してランタイム値を検査します。

10. 必要に応じて stepInto()、stepOver()、stepOut() でステップ実行します。

11. resume() を呼び出します。

12. ソースコードから一時的な debugger; ステートメントを削除します。

エージェント作者向けの重要なルール

このサーバーは人間だけでなく、ツールを使用するエージェント向けに設計されています。MCP クライアントに統合する場合は、次のルールを守ってください:

• listTargets() をスキップしないでください。

• タブが1つだけ開いていても、ターゲット URL を推測しないでください。

• connect() の前に必ずユーザーの明示的な確認を待ってください。

• reloadPage() の後、同じターン内で直ちに waitForSpecificPause() または waitForPause() を呼び出してください。

• ランタイム値を直接検査できる場合は、静的コードから挙動を説明しないでください。

• 検査後は必ず resume() を呼び出してください。

• ソースコードに一時的な debugger; ステートメントを追加した場合は、終了前に削除してください。

waitForSpecificPause のマッチング方法

waitForSpecificPause は、任意の一時停止を待つよりも信頼性が高いため、推奨される待機プリミティブです。

一時停止のマッチングには2つの戦略を使用します:

1. URL フラグメントと行番号の許容差

2. URL フラグメントと debugger-statement 一時停止理由

2番目のパスは、ソースマップ、トランスパイル、バンドルによってコンパイル後の行番号がエディタの行番号からずれる場合に重要です。

ツール呼び出しの例

ローカルの Vite アプリをデバッグするエージェントは、次のようなことを行うかもしれません:

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. ユーザーが http://127.0.0.1:5173 を確認するのを待ちます

5. connect({ targetUrl: "127.0.0.1:5173" })

6. App.jsx に debugger; を挿入します

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Chrome の起動動作

launchChrome() は専用のプロファイルを使用するため、ユーザーの通常のブラウザセッションには干渉しません。

デフォルト:

• リモートデバッグポート: 9222

• プロファイルディレクトリ: ~/.chrome-debug-profile

想定される Chrome バイナリの場所:

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux: google-chrome

• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

自動起動に失敗した場合、ツールはユーザーが手動で実行できるコマンドを返します。

ローカルプレイグラウンド

このリポジトリには test/ 配下に使い捨てのテストアプリが含まれており、実際のブラウザワークフローに対してデバッガーサーバーを試すことができます。

モックサービスを起動する

cd test/service
node src/server.js

サービスは http://127.0.0.1:3030 で待ち受けます。

Web アプリを起動する

cd test/web
pnpm install
pnpm dev

Web アプリは http://127.0.0.1:5173 で実行されます。

一時停止に便利な場所:

• test/web/src/App.jsx の loadWorkbench 内

• test/web/src/App.jsx の loadModuleDetail 内

• test/web/src/App.jsx の未完成の詳細セクション周辺

検査する価値のあるランタイムペイロード領域:

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

トラブルシューティング

ターゲットが見つからない

Chrome が --remote-debugging-port=9222 で実行され、ターゲットページが開いていることを確認してください。

targetUrl に一致するタブが複数ある

より具体的な部分文字列を渡して、一致が一意になるようにしてください。

waitForPause または waitForSpecificPause がタイムアウトする

これは次の場合に発生する可能性があります:

• ページのアクションがトリガーされなかった

• 間違ったブレークポイントが設定された

• MCP クライアント自体のリクエストタイムアウトがツール呼び出しより短い

クライアントがすぐにタイムアウトする場合は、getStatus() でポーリングするか、クライアントのタイムアウトを増やしてください。

一時停止した行番号がエディタの行と一致しない

バンドラーやトランスパイラーはコンパイル後の行番号をずらすことがあります。waitForSpecificPause() を使用し、URL フラグメントのマッチングと debugger-statement のセマンティクスに依存してください。

Chrome が自動的に起動しない

マシンがデフォルト以外の Chrome インストールパスを使用している可能性があります。返された起動コマンドを手動で実行するか、環境に合わせて実装を調整してください。

開発

pnpm install
pnpm build
node dist/index.js

実装は次の場所にあります:

• src/index.ts: MCP ツール定義とユーザー向けワークフローヒント

• src/chrome-manager.ts: Chrome DevTools Protocol の統合とデバッガー状態管理

ライセンス

MIT

Related MCP server: Chrome DevTools MCP

中文

一个面向 Chrome 断点调试的 MCP Server。

chrome-debugger-mcp 把 Chrome DevTools Protocol 的核心调试能力暴露为 MCP 工具，让 AI agent 可以连接真实的 Chrome 标签页，在运行时暂停执行、读取作用域变量、在当前调用帧中执行表达式、单步跟踪代码，并基于真实值继续任务，而不是只靠静态源码猜测行为。

它不是通用浏览器自动化工具。它的重点是运行时调试。

核心能力

• 在用户明确确认后，通过 CDP 连接真实的 Chrome 标签页

• 在断点或 debugger; 命中时暂停，并等待指定文件和行附近的 pause

• 读取当前暂停帧中的 local、closure、module 作用域变量

• 在当前调用帧里执行 JavaScript，并继续单步跟踪

• 检查完成后恢复执行，让 agent 基于真实运行时值继续工作

功能演示

演示流程：agent 拉起 Chrome，等待断点命中，读取真实作用域变量，再基于运行时事实继续执行，而不是靠猜测推进。

MCP 客户端配置

使用已发布包

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

安装方式

从 npm 使用

npx -y chrome-debugger-mcp

也可以全局安装：

npm install -g chrome-debugger-mcp

从源码运行

pnpm install
pnpm build
node dist/index.js

其他特点

• 启动带远程调试端口的独立 Chrome 实例

• 无需修改源码即可设置和移除断点

• 通过 CDP 重载页面，确保跳转后断点可靠绑定

• 当 MCP 客户端请求超时较短时，可轮询调试器状态

• 输出 _ui 结果和 logging 消息，方便客户端展示给用户

为什么适合这个场景

很多浏览器方向的 MCP 工具更擅长 DOM 操作和网络请求观察，但不擅长回答运行时调试问题。这个服务补上的是 Chrome DevTools 里最关键的那条链路：连接正确标签页、在正确时机暂停、读取真实值、必要时单步跟踪、最后恢复执行。

它也内置了 guardrails，避免 agent 出现这些常见错误：

• 猜测应该连接哪个标签页

• 没看运行时值就直接下结论

• 在 reloadPage() 和 waitForSpecificPause() 之间错误地结束当前轮次

运行要求

• 本机安装了 Google Chrome

• 使用支持 stdio MCP server 和工具调用的 MCP 客户端

• 可以访问你要调试的应用

• 如果要插入临时 debugger;，需要能访问本地源码

工具模型

这个服务通过 stdio 运行，并暴露一组 MCP tools。最核心的工具有：

• startDebuggingSession：返回推荐调试流程和 agent 行为约束

• launchChrome：启动带远程调试能力的独立 Chrome 实例

• listTargets：列出可调试标签页，并要求用户做选择

• connect：连接到已确认的目标标签页

• setBreakpoint：在不改源码的情况下通过 CDP 设置断点

• removeBreakpoint：移除通过 setBreakpoint 创建的断点

• reloadPage：通过 CDP 重载当前页面

• waitForSpecificPause：等待下一次暂停，并判断是否命中目标文件和行

• waitForPause：不做位置匹配，等待任意暂停

• getScopeVariables：读取当前暂停帧中的局部、闭包、模块作用域变量

• evaluate：在暂停调用帧中执行 JavaScript

• stepInto、stepOver、stepOut：标准单步控制

• resume：检查完毕后恢复执行

• getStatus：非阻塞方式查询是否已连接、是否已暂停

• forcePause：请求在下一条 JavaScript 语句处暂停

推荐工作流

对于 AI 客户端，建议流程是：

1. 调用 startDebuggingSession()。

2. 调用 launchChrome()，或直接复用已经开启 CDP 端口的 Chrome。

3. 调用 listTargets()，并把完整标签页列表展示给用户。

4. 等待用户明确确认要调试的页面 URL。

5. 调用 connect({ targetUrl })。

6. 在本地源码插入临时 debugger;，或者调用 setBreakpoint()。

7. 调用 reloadPage()。

8. 在同一轮里立刻调用 waitForSpecificPause()。

9. 调用 getScopeVariables() 和 evaluate() 检查运行时值。

10. 必要时使用 stepInto()、stepOver()、stepOut() 继续跟踪。

11. 调用 resume()。

12. 删除源码里临时加入的 debugger;。

给 Agent 作者的重要规则

这个服务首先是为会调用工具的 agent 设计的，而不仅仅是给人手动点工具用。接入 MCP 客户端时，建议遵守这些规则：

• 不要跳过 listTargets()。

• 即使只看到一个标签页，也不要猜测目标 URL。

• 一定要等用户明确确认后再调用 connect()。

• 调用 reloadPage() 后，必须在同一轮里立刻调用 waitForSpecificPause() 或 waitForPause()。

• 能读取运行时值时，不要只根据静态代码解释行为。

• 检查完之后一定要 resume()。

• 如果向源码里插入了临时 debugger;，结束前要清理掉。

waitForSpecificPause 如何匹配

waitForSpecificPause 是首选的等待工具，因为它比“等待任意暂停”更可靠。

它有两层匹配策略：

1. URL 片段加行号容差

2. URL 片段加 debugger-statement 暂停原因

第二层匹配对经过 source map、转译、打包后的代码尤其重要，因为编译后的行号可能和编辑器行号不完全一致。

调用序列示例

一个 agent 调试本地 Vite 应用时，调用顺序大致会像这样：

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. 等用户确认 http://127.0.0.1:5173

5. connect({ targetUrl: "127.0.0.1:5173" })

6. 在 App.jsx 插入 debugger;

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Chrome 启动行为

launchChrome() 会使用独立 profile，不会影响用户平时正在用的浏览器会话。

默认值：

• 远程调试端口：9222

• profile 目录：~/.chrome-debug-profile

默认 Chrome 可执行文件路径：

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux: google-chrome

• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

如果自动启动失败，工具会返回一个可手动执行的命令。

本地 Playground

这个仓库里有一个可丢弃的测试应用，位于 test/ 下，方便你针对真实的浏览器调试流程来调试这个服务器。

启动 mock 服务

cd test/service
node src/server.js

服务监听在 http://127.0.0.1:3030。

启动 web app

cd test/web
pnpm install
pnpm dev

web 应用运行在 http://127.0.0.1:5173。

适合暂停的地方：

• test/web/src/App.jsx 的 loadWorkbench 内

• test/web/src/App.jsx 的 loadModuleDetail 内

• test/web/src/App.jsx 的未完成 detail 部分附近

值得检查的运行时 payload 区域：

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

故障排查

找不到目标

确保 Chrome 以 --remote-debugging-port=9222 运行，并且目标页面已打开。

有多个标签页匹配 targetUrl

传入更具体的子串，让匹配变得唯一。

waitForPause 或 waitForSpecificPause 超时

可能的原因：

• 页面操作从未触发

• 设置了错误的断点

• MCP 客户端本身的请求超时比工具调用更短

如果你的客户端超时很快，请使用 getStatus() 轮询或增加客户端超时。

暂停的行号与编辑器行号不一致

打包器和转换器可能会改变编译后的行号。使用 waitForSpecificPause() 并依赖 URL 片段匹配和 debugger-statement 语义。

Chrome 无法自动启动

机器可能使用了非默认的 Chrome 安装路径。请手动运行返回的启动命令，或调整实现以匹配你的环境。

开发

pnpm install
pnpm build
node dist/index.js

实现位于：

• src/index.ts：MCP 工具定义和面向用户的流程提示

• src/chrome-manager.ts：Chrome DevTools Protocol 集成和调试器状态管理

许可证

MIT

• macOS：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux：google-chrome

• Windows：C:\Program Files\Google\Chrome\Application\chrome.exe

自動起動に失敗した場合、ツールはユーザーが手動で実行できる起動コマンドを返します。

ローカル Playground

リポジトリには、破棄可能なテストアプリが test/ に同梱されています。これを使って、このデバッグ MCP の一連の流れを直接検証できます。

mock service を起動

cd test/service
node src/server.js

サービスは http://127.0.0.1:3030 で待ち受けます。

web app を起動

cd test/web
pnpm install
pnpm dev

Web アプリは http://127.0.0.1:5173 で動作します。

ブレークポイントを設定する推奨箇所：

• test/web/src/App.jsx 内の loadWorkbench

• test/web/src/App.jsx 内の loadModuleDetail

• test/web/src/App.jsx 内の未完成の detail 領域の近く

実行時に確認する価値がある payload フィールド：

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

トラブルシューティング

targets が見つからない

Chrome が --remote-debugging-port=9222 で起動されていること、および対象ページが開かれていることを確認してください。

targetUrl が複数のタブに一致する

より具体的な URL の部分文字列を渡して、一致結果が一意になるようにしてください。

waitForPause または waitForSpecificPause がタイムアウトする

よくある原因は次のとおりです：

• ページ操作が実際にはトリガーされていない

• ブレークポイントの位置が正しくない

• MCP クライアント自身のリクエストタイムアウトがツール呼び出しよりも短い

クライアントのタイムアウトが短い場合は、getStatus() によるポーリングに切り替えるか、クライアントのタイムアウトを長くしてください。

一時停止時の行番号がエディタと一致しない

バンドルやトランスパイルにより、コンパイル後の行番号がずれます。waitForSpecificPause() を優先して使用し、URL フラグメントの一致と debugger-statement のセマンティック一致に依存してください。

Chrome が自動起動できない

マシン上の Chrome のインストールパスがデフォルトと異なる可能性があります。ツールが返した起動コマンドを直接実行するか、環境に合わせて実装を調整してください。

開発

pnpm install
pnpm build
node dist/index.js

主要な実装ファイル：

• src/index.ts：MCP ツール定義とユーザー向けワークフローのヒント

• src/chrome-manager.ts：Chrome DevTools Protocol の統合とデバッグ状態の管理

ライセンス

MIT