chrome-debugger-mcp

English | 中文

English

一个用于断点驱动 Chrome 调试的 MCP 服务器。

chrome-debugger-mcp 将 Chrome DevTools 协议原语暴露为 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

如果自动启动失败，该工具将返回用户可以手动运行的命令。

本地游乐场

此存储库在 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 协议集成和调试器状态管理

许可证

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/。你可以直接用它验证这个调试 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