chrome-debugger-mcp

English | 中文

English

An MCP server for breakpoint-driven Chrome debugging.

chrome-debugger-mcp exposes Chrome DevTools Protocol primitives as MCP tools so an AI agent can attach to a real Chrome tab, pause execution, inspect scope values, evaluate expressions inside the current call frame, and step through code with runtime facts instead of guessing from static source.

It is not a general browser automation server. The focus is runtime debugging.

Core Capabilities

• Attach to a real Chrome tab over CDP after explicit user confirmation
• Pause at breakpoints or debugger; statements and wait for the exact pause you expect
• Read local, closure, and module scope values from the paused frame
• Evaluate JavaScript in the current call frame and step execution forward
• Resume cleanly so the agent can continue with actual runtime values

Demo

Demo: the agent launches Chrome, waits for a breakpoint, inspects real scope variables, and resumes with runtime facts instead of guessing.

MCP Client Configuration

Use the published package

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

Installation

From npm

npx -y chrome-debugger-mcp

Or install it globally:

npm install -g chrome-debugger-mcp

From source

pnpm install
pnpm build
node dist/index.js

Other Highlights

• Launch a dedicated Chrome instance with remote debugging enabled
• Set and remove DevTools breakpoints without editing source code
• Reload the page through CDP so breakpoints reliably bind after navigation
• Poll debugger state when the MCP client has short request timeouts
• Emit _ui payloads and logging messages that clients can surface to the user

Why It Helps

Many browser-focused MCP tools are strong at DOM interaction and network inspection, but weak at runtime debugging. This server gives an MCP client the missing loop you would normally use in Chrome DevTools: attach to the right tab, pause at the right time, inspect real values, step if needed, and resume cleanly.

It also adds guardrails that prevent common agent mistakes:

• guessing which tab to attach to
• concluding behavior without inspecting runtime values
• ending the turn between reloadPage() and waitForSpecificPause()

Requirements

• Google Chrome installed locally
• An MCP client that supports stdio servers and tool calling
• Access to the application you want to debug
• Local source access if you plan to insert temporary debugger; statements

Tooling Model

The server runs over stdio and exposes MCP tools. The most important tools are:

• startDebuggingSession: returns the recommended debugging workflow and critical rules for agent behavior
• launchChrome: launches a dedicated Chrome instance with remote debugging enabled
• listTargets: lists available Chrome tabs and requires the user to pick one
• connect: attaches to the confirmed tab
• setBreakpoint: creates a CDP breakpoint without modifying source files
• removeBreakpoint: removes a breakpoint created by setBreakpoint
• reloadPage: reloads the current page through CDP
• waitForSpecificPause: waits for the next pause and checks whether it matches a target file and line
• waitForPause: waits for any pause without location matching
• getScopeVariables: reads local, closure, and module scope values from the paused frame
• evaluate: executes JavaScript in the paused call frame
• stepInto, stepOver, stepOut: standard execution control
• resume: resumes execution after inspection
• getStatus: non-blocking polling for connected or paused state
• forcePause: requests a pause at the next JavaScript statement

Recommended Workflow

For AI clients, the intended flow is:

1. Call startDebuggingSession().
2. Call launchChrome() or use an already-running Chrome instance with a CDP port.
3. Call listTargets() and show the full tab list to the user.
4. Wait for the user to confirm the exact page URL.
5. Call connect({ targetUrl }).
6. Insert a temporary debugger; statement in local source code, or call setBreakpoint().
7. Call reloadPage().
8. Immediately call waitForSpecificPause() in the same turn.
9. Call getScopeVariables() and evaluate() to inspect runtime values.
10. Step if necessary with stepInto(), stepOver(), or stepOut().
11. Call resume().
12. Remove any temporary debugger; statements from source code.

Important Rules For Agent Authors

This server is designed for tool-using agents, not only for humans. If you are integrating it into an MCP client, keep these rules:

• Never skip listTargets().
• Never guess the target URL, even if only one tab is open.
• Always wait for explicit user confirmation before connect().
• After reloadPage(), immediately call waitForSpecificPause() or waitForPause() in the same turn.
• Do not explain behavior from static code when runtime values can be inspected directly.
• Always resume() after inspection.
• If you added temporary debugger; statements to source code, remove them before finishing.

How waitForSpecificPause Matches

waitForSpecificPause is the preferred waiting primitive because it is more reliable than waiting for an arbitrary pause.

It matches a pause using two strategies:

1. URL fragment plus line tolerance
2. URL fragment plus debugger-statement pause reason

The second path matters when source maps, transpilation, or bundling shift compiled line numbers away from editor line numbers.

Example Tool Sequence

An agent debugging a local Vite app might do something like this:

1. launchChrome({ dryRun: true })
2. launchChrome()
3. listTargets()
4. Wait for the user to confirm http://127.0.0.1:5173
5. connect({ targetUrl: "127.0.0.1:5173" })
6. Insert debugger; in App.jsx
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 Launch Behavior

launchChrome() uses a dedicated profile so it does not interfere with the user's normal browser session.

Defaults:

• remote debugging port: 9222
• profile directory: ~/.chrome-debug-profile

Expected Chrome binary locations:

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux: google-chrome
• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

If automatic launch fails, the tool returns a command the user can run manually.

Local Playground

This repository includes a disposable test app under test/ so you can exercise the debugger server against a realistic browser workflow.

Start the mock service

cd test/service
node src/server.js

The service listens on http://127.0.0.1:3030.

Start the web app

cd test/web
pnpm install
pnpm dev

The web app runs on http://127.0.0.1:5173.

Useful places to pause:

• test/web/src/App.jsx inside loadWorkbench
• test/web/src/App.jsx inside loadModuleDetail
• test/web/src/App.jsx around the unfinished detail sections

Runtime payload areas worth inspecting:

• summaryCards
• modules
• apiContracts
• nextActions
• responseShape

Troubleshooting

No targets found

Make sure Chrome is running with --remote-debugging-port=9222 and the target page is open.

More than one tab matches targetUrl

Pass a more specific substring so the match becomes unique.

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 消息，方便客户端展示给用户