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

... View full README on GitHub