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

1. Start your application with --inspect-brk:

   node --inspect-brk=9229 app.js

2. Get the WebSocket URL:

   curl http://localhost:9229/json

3. Connect the debugger:

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

4. Set breakpoints:

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

5. Resume execution to hit the breakpoint:

   resume_execution(session_id: "...")
   

6. 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")
   

7. 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