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

1. Build the server:

   npm install npm run build

2. For Project-Specific Use: The .mcp.json file is already configured in this project

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

4. For Global Use: Copy the .mcp.json to 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 debugging

• kill_process - Terminate processes by PID

• list_processes - Show all managed processes

Debugging

• attach_debugger - Connect to debug port

• set_breakpoint - Set breakpoints with optional conditions

  • Important: Use full file:// URLs for reliable breakpoint hits

  • Example: file:///Users/you/project/script.js

• step_debug - Step through code (next/step/continue/out)

• pause_execution - Manually pause a running process

• evaluate_expression - Evaluate expressions in debug context

Resources

• debug://session - Current debug session state

• debug://processes - List of managed processes

Example Usage

1. Start a Node.js process:

   Use the start_node_process tool with script: "example-app.js"

2. Attach debugger:

   Use attach_debugger tool with the port returned from step 1

3. 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-brk flag 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:

Then use the MCP tools to debug it!

Debug the MCP Server