MCP JS Debugger

You use the MCP JS Debugger to attach Chrome DevTools Protocol debugging capabilities to CDP-compatible targets (like Node.js or Chrome). This enables you to set breakpoints, inspect call stacks with source maps, evaluate expressions, and step through code to diagnose and fix issues in JavaScript and TypeScript applications.

How to use

Connect to a CDP-compatible debugger from your MCP client to start debugging sessions. You can attach to a running target, set breakpoints in original or generated sources, and control execution (pause, resume, step over, step into, step out). When source maps are available, you’ll see original source locations in call stacks and can map generated positions back to the original files.

How to install

Prerequisites: you need Node.js 18.0.0 or later and npm. Make sure you have a working Node.js environment before proceeding.

Install dependencies and build the MCP JS Debugger locally.

npm install
npm run build

Configuration and usage notes

To integrate with Claude Code, add the MCP server as a tool in your Claude Code configuration. You have two options:

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

Or declare the MCP server in your project configuration file with the following snippet:

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

Detailed usage workflow

1. Start your Node.js application with the inspector enabled.

node --inspect-brk=9229 app.js

2. Retrieve the WebSocket URL for the inspector (example):

curl http://localhost:9229/json

3. Connect the debugger from your MCP client using the WebSocket URL you obtained.

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

4. Manage breakpoints and execution as needed, for example: set breakpoints, resume, pause, step over/into/out, and inspect call stacks and variables.

Source map support and debugging essentials

The server automatically loads source maps for transpiled code. When available, you can:

• View original source locations in call stacks

• Set breakpoints on original source files

• Map generated positions back to original sources with get_original_location

Development

Use these commands to develop and test locally:

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Architecture overview

Key components include a Chrome DevTools Protocol client wrapper, a session manager for multiple debugging sessions, a source map manager for position mapping, the MCP server itself, and TypeScript type definitions.

Notes on requirements and licensing

Requires Node.js 18.0.0 or later and a CDP-compatible debug target (Node.js, Chrome, Edge, etc.). The server is released under the Apache-2.0 license.

Available tools

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