chrome-debugger-mcp
chrome-debugger-mcp
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:在暂停的调用帧中执行 JavaScriptstepInto、stepOver、stepOut:标准执行控制resume:检查后恢复执行getStatus:非阻塞轮询连接或暂停状态forcePause:请求在下一条 JavaScript 语句处暂停
推荐工作流
对于 AI 客户端,预期流程是:
调用
startDebuggingSession()。调用
launchChrome()或使用已运行并带有 CDP 端口的 Chrome 实例。调用
listTargets()并向用户显示完整的标签页列表。等待用户确认确切的页面 URL。
调用
connect({ targetUrl })。在本地源代码中插入临时
debugger;语句,或调用setBreakpoint()。调用
reloadPage()。在同一轮中立即调用
waitForSpecificPause()。调用
getScopeVariables()和evaluate()检查运行时值。如有必要,使用
stepInto()、stepOver()或stepOut()单步执行。调用
resume()。从源代码中删除任何临时的
debugger;语句。
给 Agent 作者的重要规则
该服务器专为使用工具 agent 设计,而不仅仅是为人类设计。如果你将其集成到 MCP 客户端中,请遵守以下规则:
切勿跳过
listTargets()。切勿猜测目标 URL,即使只打开了一个标签页。
在
connect()之前始终等待用户明确确认。在
reloadPage()之后,在同一轮中立即调用waitForSpecificPause()或waitForPause()。当可以直接检查运行时值时,不要根据静态代码解释行为。
检查后始终
resume()。如果向源代码中添加了临时
debugger;语句,请在完成前将其删除。
waitForSpecificPause 如何匹配
waitForSpecificPause 是首选的等待原语,因为它比等待任意暂停更可靠。
它使用两种策略匹配暂停:
URL 片段加行容差
URL 片段加
debugger-statement暂停原因
当源映射、转译或打包将编译后的行号从编辑器行号移开时,第二种路径很重要。
示例工具序列
调试本地 Vite 应用的 agent 可能会执行以下操作:
launchChrome({ dryRun: true })launchChrome()listTargets()等待用户确认
http://127.0.0.1:5173connect({ targetUrl: "127.0.0.1:5173" })在
App.jsx中插入debugger;reloadPage()waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })getScopeVariables()evaluate({ expression: "payload.modules" })resume()
Chrome 启动行为
launchChrome() 使用专用配置文件,因此不会干扰用户的正常浏览器会话。
默认值:
远程调试端口:
9222配置文件目录:
~/.chrome-debug-profile
预期的 Chrome 可执行文件位置:
macOS:
/Applications/Google Chrome.app/Contents/MacOS/Google ChromeLinux:
google-chromeWindows:
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 devWeb 应用运行在 http://127.0.0.1:5173。
有用的暂停位置:
test/web/src/App.jsx中的loadWorkbench内部test/web/src/App.jsx中的loadModuleDetail内部test/web/src/App.jsx中未完成的详细信息部分附近
值得检查的运行时负载区域:
summaryCardsmodulesapiContractsnextActionsresponseShape
故障排除
未找到目标
确保 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: MCP JS Debugger
中文
一个面向 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:在暂停调用帧中执行 JavaScriptstepInto、stepOver、stepOut:标准单步控制resume:检查完毕后恢复执行getStatus:非阻塞方式查询是否已连接、是否已暂停forcePause:请求在下一条 JavaScript 语句处暂停
推荐工作流
对于 AI 客户端,建议流程是:
调用
startDebuggingSession()。调用
launchChrome(),或直接复用已经开启 CDP 端口的 Chrome。调用
listTargets(),并把完整标签页列表展示给用户。等待用户明确确认要调试的页面 URL。
调用
connect({ targetUrl })。在本地源码插入临时
debugger;,或者调用setBreakpoint()。调用
reloadPage()。在同一轮里立刻调用
waitForSpecificPause()。调用
getScopeVariables()和evaluate()检查运行时值。必要时使用
stepInto()、stepOver()、stepOut()继续跟踪。调用
resume()。删除源码里临时加入的
debugger;。
给 Agent 作者的重要规则
这个服务首先是为会调用工具的 agent 设计的,而不仅仅是给人手动点工具用。如果你要把它接入自己的 MCP 客户端,建议遵守这些规则:
不要跳过
listTargets()。即使只看到一个标签页,也不要猜测目标 URL。
一定要等用户明确确认后再调用
connect()。调用
reloadPage()后,必须在同一轮里立刻调用waitForSpecificPause()或waitForPause()。能读取运行时值时,不要只根据静态代码解释行为。
检查完之后一定要
resume()。如果向源码里插入了临时
debugger;,结束前要清理掉。
waitForSpecificPause 如何匹配
waitForSpecificPause 是首选的等待工具,因为它比"等待任意暂停"更可靠。
它有两层匹配策略:
URL 片段加行号容差
URL 片段加
debugger-statement暂停原因
第二层匹配对经过 source map、转译、打包后的代码尤其重要,因为编译后的行号可能和编辑器行号不完全一致。
调用序列示例
一个 agent 调试本地 Vite 应用时,调用顺序大致会像这样:
launchChrome({ dryRun: true })launchChrome()listTargets()等用户确认
http://127.0.0.1:5173connect({ targetUrl: "127.0.0.1:5173" })在
App.jsx插入debugger;reloadPage()waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })getScopeVariables()evaluate({ expression: "payload.modules" })resume()
Chrome 启动行为
launchChrome() 会使用独立 profile,不会影响用户平时正在用的浏览器会话。
默认值:
远程调试端口:
9222profile 目录:
~/.chrome-debug-profile
默认 Chrome 可执行文件路径:
macOS:
/Applications/Google Chrome.app/Contents/MacOS/Google ChromeLinux:
google-chromeWindows:
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 devWeb 应用运行在 http://127.0.0.1:5173。
建议下断点的位置:
test/web/src/App.jsx里的loadWorkbenchtest/web/src/App.jsx里的loadModuleDetailtest/web/src/App.jsx里尚未完成的 detail 区域附近
值得在运行时查看的 payload 字段:
summaryCardsmodulesapiContractsnextActionsresponseShape
故障排查
找不到 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
Available Tools
18 toolsconnectA
[STEP 3] Connect the debugger to a specific Chrome tab. MANDATORY: call listTargets first, show the list to the user, wait for their explicit URL confirmation, then call this. NEVER guess the URL. NEVER skip user confirmation — even if only one tab is visible. targetUrl must be a unique substring of the tab URL the user confirmed (e.g. "localhost:5173"). Relay the "_ui" field from the response to the user.
Inputs: targetUrl (required), port.
disconnectA
Disconnect the current Chrome debugging session and clear in-memory pause state. Use this to explicitly end a debug session before connecting again.
Inputs: no named parameters.
evaluateA
[STEP 6b] Evaluate any JavaScript expression in the context of the currently paused call frame. Use this to inspect nested objects, call methods, compute derived values, or verify conditions at runtime. Complements getScopeVariables for values not directly visible in scope (e.g. this.state, JSON.stringify(obj)).
Inputs: expression (required), frameIndex.
forcePauseA
Force the debugger to pause at the very next JavaScript statement. Useful when you cannot modify source code to add debugger; and setBreakpoint is not feasible.
Inputs: no named parameters.
getScopeVariablesA
[STEP 6a] Read all scope variables (local, closure, module) at the currently paused call frame. Call this immediately after waitForSpecificPause or waitForPause returns. Results are grouped by scope type; global scope is skipped. Use frameIndex=1, 2, ... to inspect variables in parent call frames up the stack.
Inputs: frameIndex.
getStatusA
Non-blocking: return current connection and pause state immediately without waiting. Use this to poll for pause instead of waitForPause when the MCP client has a short request timeout (e.g. MCP Inspector ~10s). Returns: connected, paused, targetUrl, pauseReason, hitBreakpoints, callStack.
Inputs: no named parameters.
launchChromeA
[STEP 1] Launch a dedicated Chrome instance with remote debugging enabled (default port 9222). Uses --user-data-dir=~/.chrome-debug-profile so your normal Chrome keeps running (dual-instance). Auto-detects if the debug port is already active and skips launch (alreadyRunning=true). Use dryRun=true to preview the command — show it to the user and ask for confirmation before executing. Set openDevTools=true to automatically open DevTools panel for every new tab. If automatic launch does not succeed, relay the returned command to the user and ask them to run it manually. Relay the "_ui" field from the response to the user.
Inputs: url, port, dryRun, chromePath, +2 more.
listTargetsA
[STEP 2] List all open Chrome tabs available for debugging. MANDATORY: show the full list to the user and ask "Which URL do you want to debug?" NEVER skip this step, NEVER guess — even if only one tab is open. Wait for the user's explicit reply before proceeding to connect(). Relay the "_ui" field from the response to the user.
Inputs: port.
reloadPageA
[STEP 5a] Reload the connected page via Chrome DevTools Protocol. More reliable than manual browser refresh — maintains the CDP connection and ensures debugger; statements and setBreakpoint() calls resolve correctly when scripts reload. Always call this after inserting debugger; in source code or after setBreakpoint(), before waitForSpecificPause/waitForPause.
⚠️ CRITICAL TURN RULE: After this tool returns, you MUST immediately call waitForSpecificPause (or waitForPause) in the SAME AI turn — do NOT end your turn here. waitForSpecificPause is a blocking call that will notify the user to trigger the page action and wait for the breakpoint internally. If you end your turn after reloadPage, the session will break.
Inputs: ignoreCache.
removeBreakpointA
Remove a previously set CDP breakpoint by its ID (returned by setBreakpoint).
Inputs: breakpointId (required).
resumeA
[STEP 8] Resume script execution after collecting all needed variable data — ends the current pause. After calling resume, remove all temporary debugger; statements added to source code during this session. Relay the "_ui" field from the response to the user.
Inputs: no named parameters.
setBreakpointA
Set a breakpoint at a specific script URL and line number via CDP — no source code modification needed. Use a full URL (https://...) for exact match, or a partial filename/keyword for regex match. Alternative to inserting debugger; when you cannot modify the source file. After setting, call reloadPage() to ensure the breakpoint resolves correctly.
Inputs: url (required), line (required), column, condition.
startDebuggingSessionA
CALL THIS FIRST whenever browser-side debugging is needed — before any other tool.
Auto-trigger when user mentions any of: debug, breakpoint, debugger, inspect, trace, step through, runtime value, variable value, why is this, implement based on API response, bug, error, unexpected behavior, not working, check this, confirm this.
Returns the complete debugging workflow and critical rules. The response contains a "_ui" field — relay it to the user verbatim.
Inputs: no named parameters.
stepIntoA
[STEP 7] BLOCKING: step into the next function call, then wait until the debugger pauses again. Follow with getScopeVariables() to observe inner-function state.
Inputs: timeout.
stepOutA
[STEP 7] BLOCKING: step out of the current function and wait until the debugger pauses again in the caller. Use to observe the return value and the state of the calling context.
Inputs: timeout.
stepOverA
[STEP 7] BLOCKING: step over the current statement without entering function calls, then wait until the debugger pauses again. Follow with getScopeVariables() to observe how local variables change.
Inputs: timeout.
waitForPauseA
[STEP 5b — FALLBACK] BLOCKING call — waits until ANY debugger pause occurs (breakpoint, debugger; statement, or exception). Before blocking, sends a notification to the user to trigger the page action. Must be called IMMEDIATELY after reloadPage() in the SAME AI turn — do NOT end your turn before calling this. Prefer waitForSpecificPause when you know the exact file and line — it uses smarter two-tier matching. Use this only when the target location is unknown or when setBreakpoint is used without a specific line.
Inputs: timeout, actionHint.
waitForSpecificPauseA
[STEP 5b — PREFERRED] BLOCKING call — waits for the next debugger pause, then checks if it matches the target location.
⚠️ NO AUTO-RESUME: execution stays paused after this returns, regardless of matched value. You decide what to do based on the "matched" field in the response: matched=true → call getScopeVariables() immediately to read variables matched=false → the wrong breakpoint fired; call resume() to continue, then call waitForSpecificPause() again if you need to wait for the next pause.
Must be called IMMEDIATELY after reloadPage() in the SAME AI turn. Before blocking, sends a notification to the user to trigger the page action. Editor line N → pass line=N-1 (CDP uses 0-based line numbers). Relay the "_ui" field from the response to the user once it returns.
Inputs: line (required), urlFragment (required), timeout, actionHint, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Core tools are distinct, but waitForPause vs waitForSpecificPause have heavily overlapping blocking-wait semantics that could easily cause misselection. getScopeVariables vs evaluate also blur boundaries, and startDebuggingSession's auto-trigger instructions create confusion about when the workflow tool is appropriate.
Consistently camelCase with mostly verb-first names, and the stepInto/stepOver/stepOut family is clean. Minor deviations: 'evaluate' and 'resume' are bare verbs without a resource prefix, and the verb vocabulary is somewhat varied (launch, list, connect, set, force, reload), but no convention mixing.
18 tools is in the heavy range, and several could be consolidated (waitForPause/waitForSpecificPause, getStatus overlapping with wait functionality, startDebuggingSession being more of a workflow document than a tool). Not egregiously bloated—each tool does meaningful work—but the set could be trimmed to ~14-15 without losing expressiveness.
Covers the full debug lifecycle: launch, connect, breakpoints, pause, inspect, step, resume, and status. Minor gaps: no way to list active breakpoints, and the workflow skips STEP 4 entirely. Exception handling is only mentioned tangentially in waitForPause. Otherwise, a well-covered surface that achieves its debugging purpose.
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Build, run, debug, test and ship Chrome, Firefox, Edge and Safari extensions from your AI agent.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser for automation, debugging, performance analysis, network monitoring, and DOM interaction through Chrome DevTools Protocol.Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI assistants to debug JavaScript and TypeScript applications by connecting to Chrome DevTools Protocol-compatible debuggers, allowing them to set breakpoints, step through code, inspect variables, and evaluate expressions with full source map support.182Apache 2.0
- AlicenseNot gradedqualityCmaintenanceWraps Chrome DevTools Protocol to provide AI agents with low-level browser debugging tools including breakpoints, stack traces, stepping, network interception, and source maps.79 npm1MIT
- AlicenseBqualityBmaintenanceEnables AI agents to debug code and automate browsers using Chrome DevTools Protocol, supporting breakpoints, variable inspection, and replayable interaction recording.35611 npm19MIT