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.

Run

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

npx -y mcp-debugger-node@beta

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

The project is still in beta, so @beta is recommended until the first stable 1.0.0 release.

Codex

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

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

Claude Code

Use the Claude Code MCP CLI:

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

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@beta"]
    }
  }
}

Other MCP Clients

Use a stdio server entry with:

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

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 get_variables or evaluate.

5. Use step_over or step_into 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 get_variables 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"}
get_variables
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.

step_over

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

step_into

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

get_variables

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.