Node.js Debugger MCP Server
An MCP server that provides Node.js debugging capabilities with process management for AI agents.
Features
- Process Management: Start/stop Node.js processes with debugging enabled
- Debugging Tools: Set breakpoints, step through code, evaluate expressions
- Inspector Integration: Connect to Node.js Inspector API
- AI Agent Friendly: Designed for long-running debugging sessions
Installation
-
Build the server:
npm install npm run build -
For Project-Specific Use: The
.mcp.jsonfile is already configured in this project -
For User-Wide Use: Add to your global Claude Code configuration:
claude mcp add --scope user debugger-mcp node /absolute/path/to/debugger-mcp/build/index.js -
For Global Use: Copy the
.mcp.jsonto your projects or add to global config
Usage with Claude Code
Once configured, you'll have access to these tools in Claude Code:
Process Management
start_node_process- Launch Node.js scripts with debuggingkill_process- Terminate processes by PIDlist_processes- Show all managed processes
Debugging
attach_debugger- Connect to debug portset_breakpoint- Set breakpoints with optional conditions- Important: Use full
file://URLs for reliable breakpoint hits - Example:
file:///Users/you/project/script.js
- Important: Use full
step_debug- Step through code (next/step/continue/out)pause_execution- Manually pause a running processevaluate_expression- Evaluate expressions in debug context
Resources
debug://session- Current debug session statedebug://processes- List of managed processes
Example Usage
-
Start a Node.js process:
Use the start_node_process tool with script: "example-app.js" -
Attach debugger:
Use attach_debugger tool with the port returned from step 1 -
Set breakpoints and debug:
# Set a breakpoint using full file URL Use set_breakpoint tool with: - file: "file:///absolute/path/to/example-app.js" - line: 5 # Control execution Use step_debug tool with action: "continue"
Key Features
- Automatic Pause on Start: Uses
--inspect-brkflag to pause at first line - Full Chrome DevTools Protocol: Real debugging, not simulation
- Reliable Breakpoints: Use
file://URLs for consistent breakpoint hits - Process Management: Track and manage multiple debugging sessions
Testing
Test with the included example app:
node --inspect=9229 example-app.js
Then use the MCP tools to debug it!
Debug the MCP Server
npm run inspector