MCP JS Debugger

An MCP (Model Context Protocol) server that exposes Chrome DevTools Protocol debugging capabilities, enabling AI assistants to debug JavaScript and TypeScript applications.

Features

Connect to any CDP-compatible debugger (Node.js, Chrome, Edge)
Set, list, and remove breakpoints
Step through code (over, into, out)
Inspect call stacks with source map support
Evaluate expressions in any stack frame
View and modify variables
Pause on exceptions
Full source map support for debugging transpiled code

Installation

npm install
npm run build

Claude Code integration

Add to your Claude Code configuration:

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

Or add to .mcp.json:

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

Usage

Starting a debug target

Start your Node.js application with the inspector:

# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js

# Or start without pausing
node --inspect=9229 your-script.js

Available tools

Tool	Description
`connect_debugger`	Connect to a CDP endpoint via WebSocket URL
`disconnect_debugger`	Disconnect from a debugging session
`set_breakpoint`	Set a breakpoint by URL and line number
`remove_breakpoint`	Remove a breakpoint by ID
`list_breakpoints`	List all breakpoints in a session
`resume_execution`	Resume execution after pause
`step_over`	Step over the current statement
`step_into`	Step into a function call
`step_out`	Step out of the current function
`pause_execution`	Pause running execution
`get_call_stack`	Get the current call stack with source locations
`evaluate_expression`	Evaluate a JavaScript expression
`get_scope_variables`	Get variables in a scope
`set_variable_value`	Modify a variable's value
`set_pause_on_exceptions`	Configure exception handling
`get_original_location`	Map generated to original source location
`get_script_source`	Get script source code
`list_scripts`	List loaded scripts

Example workflow

Start your application with --inspect-brk:
```
node --inspect-brk=9229 app.js
```
Get the WebSocket URL:
```
curl http://localhost:9229/json
```

Connect the debugger:

connect_debugger(websocket_url: "ws://localhost:9229/<id>")

Set breakpoints:

set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)

Resume execution to hit the breakpoint:
```
resume_execution(session_id: "...")
```

Inspect state when paused:

get_call_stack(session_id: "...")
get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
evaluate_expression(session_id: "...", expression: "myVariable")

Continue debugging:

step_over(session_id: "...")
resume_execution(session_id: "...")

Source map support

The server automatically loads source maps for transpiled code (TypeScript, bundled JavaScript, etc.). When source maps are available:

Call stacks show original source locations
Breakpoints can be set on original source files
get_original_location maps generated positions to original source
get_script_source can return original source content

Development

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Architecture

cdp-client.ts - Low-level Chrome DevTools Protocol client wrapper
session-manager.ts - Manages multiple debugging sessions
source-map-manager.ts - Handles source map loading and position mapping
server.ts - MCP server implementation with tool handlers
types.ts - TypeScript type definitions

Requirements

Node.js 18.0.0 or later
A CDP-compatible debug target (Node.js, Chrome, Edge, etc.)

Licence

Apache-2.0

mcp-js-debugger