mcp-debugger-node

MCP server for debugging Node.js programs through the V8 Inspector Protocol.

This server gives an AI agent debugger-style tools: start a Node process under --inspect-brk, set breakpoints, continue execution, wait for pauses, step, inspect variables, and evaluate expressions in the current call frame.

[!WARNING] This server starts whatever command is provided in the reset target config. Only use it in trusted local development environments. A target config can run arbitrary commands with your user permissions.

Run

This package is meant to be started by an MCP client over stdio:

npx -y mcp-debugger-node

You usually do not run that command by hand. Instead, add it to your agent or editor MCP configuration.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.node-debugger]
command = "npx"
args = ["-y", "mcp-debugger-node"]

Claude Code

Use the Claude Code MCP CLI:

claude mcp add node-debugger -- npx -y mcp-debugger-node

For a project-local config, run that command from the project you want to configure.

GitHub Copilot in VS Code

Create or update .vscode/mcp.json:

{
  "servers": {
    "node-debugger": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-debugger-node"]
    }
  }
}

Other MCP Clients

Use a stdio server entry with:

{
  "command": "npx",
  "args": ["-y", "mcp-debugger-node"]
}

Quick Start

Start a debug session by calling reset with an explicit target:

{
  "target": {
    "cwd": "/path/to/project",
    "command": "node",
    "args": ["--inspect-brk=0", "server.js"]
  }
}

For a CommonJS TypeScript project using ts-node:

{
  "target": {
    "cwd": "/path/to/project",
    "command": "node",
    "args": ["--inspect-brk=0", "-r", "ts-node/register", "src/index.ts"]
  }
}

For an ESM TypeScript project:

{
  "target": {
    "cwd": "/path/to/project",
    "command": "node",
    "args": ["--inspect-brk=0", "--loader", "ts-node/esm", "src/index.ts"]
  }
}

The target must include --inspect-brk=0. The server reads the inspector URL from the target process stderr and connects to it.

Common Workflow

For simple scripts:

1. Call reset with a target.
2. Call set_breakpoint.
3. Call resume.
4. Call getvariables or evaluate.
5. Use stepover or stepinto as needed.

For event-driven servers:

1. Call reset with a target.
2. Call set_breakpoint in the endpoint or handler.
3. Call continue.
4. Trigger the event with curl, a browser, a test runner, or another tool.
5. Call wait_for_pause.
6. Inspect runtime state with getvariables and evaluate.
7. Call continue again to let the request finish.

Example endpoint debugging flow:

{
  "urlRegex": "server\\.js$",
  "lineNumber": 42
}

Then:

continue
curl http://localhost:3000/api/users
wait_for_pause
evaluate {"expression":"req.url"}
getvariables
continue

Tools

reset

Restart the debug session with a fresh Node inspector process.

Input:

{
  "target": {
    "cwd": "/path/to/project",
    "command": "node",
    "args": ["--inspect-brk=0", "server.js"],
    "env": {
      "NODE_ENV": "development"
    }
  }
}

env is optional and is merged with the MCP server environment.

set_breakpoint

Set a breakpoint by matching a script URL with a regex.

Input:

{
  "urlRegex": "server\\.js$",
  "lineNumber": 10
}

lineNumber is zero-based, matching the Chrome DevTools Protocol.

set_pause_on_exceptions

Configure exception pause behavior.

Input:

{
  "state": "uncaught"
}

Allowed states:

• none
• uncaught
• all

The default is uncaught.

continue

Resume execution and return immediately.

Use this when some external action needs to trigger the breakpoint, such as a curl request or browser interaction.

wait_for_pause

Wait until the debugged process pauses and return the current location.

Useful after continue when another tool is triggering the application.

resume

Resume execution and wait for the next pause.

This is convenient for scripts where the next pause will happen without an external trigger.

stepover

Step over the current statement and wait for the next pause.

stepinto

Step into the next function call and wait for the next pause.

getvariables

Get variables for the latest paused call frame scope.

evaluate

Evaluate JavaScript in the latest paused call frame.

Input:

{
  "expression": "JSON.stringify(req.body)"
}

Exception Reporting

The debugger pauses on uncaught exceptions by default. When an exception pause happens, the pause result includes exception metadata:

{
  "reason": "exception",
  "lineNumber": 8,
  "columnNumber": 3,
  "exception": {
    "className": "Error",
    "description": "Error: file is not a database ..."
  }
}

This lets agents diagnose startup crashes and runtime failures without reading server logs.