Chrome Debugger MCP

chrome-debugger-mcp

English | 中文

English

一款用于断点驱动式 Chrome 调试的 MCP 服务。

chrome-debugger-mcp 将 Chrome DevTools Protocol 基础功能作为 MCP 工具提供，让 AI Agent 可以连接到真实的 Chrome 标签页、暂停执行、检查作用域值、在当前调用帧中计算表达式，并根据运行时信息逐步执行代码，而不是根据静态源码猜测。

它不是通用的浏览器自动化服务，而是专注于运行时调试。

核心功能

• 经用户明确确认后，通过 CDP 连接到真实的 Chrome 标签页
• 在断点或 debugger; 语句处暂停，并等待预期的准确暂停
• 读取暂停帧中的局部、闭包和模块作用域值
• 在当前调用帧中执行 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 实例
• 无需编辑源码即可设置和移除 DevTools 断点
• 通过 CDP 重新加载页面，确保导航后断点可靠地绑定
• 在 MCP 客户端请求超时时间较短时，轮询调试器状态
• 发出客户端可以呈现给用户的 _ui 载荷和日志消息

优势

许多面向浏览器的 MCP 工具擅长 DOM 交互和网络检查，但不擅长运行时调试。此服务为 MCP 客户端提供了通常在 Chrome DevTools 中使用的完整调试流程：连接到正确的标签页，在合适的时机暂停，检查实际值，按需逐步执行，然后顺利恢复执行。

它还提供了防护措施，避免 Agent 常见的错误：

• 猜测要连接哪个标签页
• 不检查运行时值就断定行为
• 在 reloadPage() 和 waitForSpecificPause() 之间结束本轮操作

要求

• 本地已安装 Google Chrome
• 支持 stdio 服务和工具调用的 MCP 客户端
• 拥有要调试的应用的访问权限
• 如果计划插入临时的 debugger; 语句，则需要访问本地源码

工具模型

此服务通过 stdio 运行，并提供 MCP 工具。最重要的工具包括：

• startDebuggingSession：返回建议的调试工作流以及 Agent 行为的关键规则
• 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; 语句。

Agent 作者的重要规则

此服务面向使用工具的 Agent，而不仅仅是人类。如果你要将其集成到 MCP 客户端中，请遵守以下规则：

• 绝不要跳过 listTargets()。
• 绝不要猜测目标 URL，即使只打开了一个标签页也不例外。
• 在调用 connect() 之前，务必等待用户明确确认。
• 调用 reloadPage() 后，务必在同一轮中立即调用 waitForSpecificPause() 或 waitForPause()。
• 如果可以直接检查运行时值，就不要根据静态代码解释行为。
• 检查后务必调用 resume()。
• 如果向源代码中添加了临时的 debugger; 语句，完成前务必将其移除。

waitForSpecificPause 的匹配方式

waitForSpecificPause 是首选的等待原语，因为它比等待任意暂停更可靠。

它通过两种策略匹配暂停：

1. URL 片段加行号容差
2. URL 片段加 debugger-statement 暂停原因

当源映射、转译或打包导致编译后的行号与编辑器中的行号不一致时，第二种方式尤为重要。

工具调用顺序示例

调试本地 Vite 应用时，Agent 可能会执行如下操作：

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

如果自动启动失败，工具会返回一条可供用户手动运行的命令。

本地 Playground

此代码库在 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 or waitForSpecificPause times out

This can happen when:

• the page action was never triggered
• the wrong breakpoint was set
• the MCP client itself has a shorter request timeout than the tool call

If your client times out quickly, use getStatus() to poll or increase the client timeout.

The paused line number does not match the editor line

Bundlers and transpilers can shift compiled line numbers. Use waitForSpecificPause() and rely on URL fragment matching plus debugger-statement semantics.

Chrome does not launch automatically

The machine may use a non-default Chrome install path. Run the returned launch command manually or adjust the implementation to match your environment.

Development

pnpm install
pnpm build
node dist/index.js

The implementation lives in:

• src/index.ts: MCP tool definitions and user-facing workflow hints
• src/chrome-manager.ts: Chrome DevTools Protocol integration and debugger state management

License

MIT

中文

一个面向 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/ 目录。你可以直接用它验证此调试 MCP 的完整链路。

启动 mock service

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 中尚未完成的 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