Node.js Debugger

This MCP Server provides Node.js debugging capabilities with built-in process management for AI agents. You can start and stop Node.js processes with debugging enabled, connect to the Node.js Inspector, set breakpoints, and step through code in long-running sessions.

How to use

You interact with this MCP server through an MCP client to manage Node.js debugging sessions. Start a Node.js process with debugging enabled, attach the debugger, set breakpoints using full file URLs, and step through code. You can pause, evaluate expressions, and monitor the current debug session and managed processes.

Typical workflows include starting a debug-enabled Node.js script, connecting the inspector, hitting a breakpoint, and then stepping through code or continuing execution. You can manage multiple debugging sessions concurrently and pause any running process when needed.

Key actions you’ll perform regularly:

• Start a Node.js process with debugging enabled
• Attach to the debug port and inspect the runtime
• Set breakpoints with reliable file URLs
• Step through code or evaluate expressions in the debug context
• List and terminate managed processes as needed
• Retrieve the current debug session state and the list of processes

How to install

Prerequisites you need on your machine:
- Node.js (LTS version recommended)
- npm (comes with Node.js) or an equivalent package manager
- A shell or terminal to run commands

Step-by-step installation and setup commands:
1) Install dependencies and build the MCP server

npm install npm run build

2) For project-specific use, ensure the MCP configuration file is prepared in your project. If you want to use the server across projects, you can add it to your global MCP configuration.

3) Configure the MCP server for user-wide usage (example). This makes the server available under your MCP tooling for all projects:

claude mcp add --scope user debugger-mcp node /absolute/path/to/debugger-mcp/build/index.js

4) To enable global usage, copy the configuration to your global config or apply it in your projects as needed.

Notes and tips

• Automatic pause on start: the server can pause at the first line of the Node.js script using the appropriate flag so you can inspect initialization.

• Full Chrome DevTools Protocol: you get real debugging capabilities, not a simulated experience. Connect to the Node.js Inspector API to control execution and inspect state.

• Reliable breakpoint hits: use full file URLs (file://) to ensure breakpoints are consistently hit during debugging.

• Process management: you can track and manage multiple debugging sessions, starting and stopping processes as needed.

Available tools

start_node_process

Launch Node.js scripts with debugging enabled to begin a new debugging session.

kill_process

Terminate a managed Node.js process by its PID.

list_processes

Display all currently managed debugging processes.

attach_debugger

Connect to the Node.js Inspector port to begin debugging an active process.

set_breakpoint

Set a breakpoint using a full file URL and optional condition to pause execution at a specific line.

step_debug

Control execution by stepping through code (step, next, continue, out) within the debug session.

pause_execution

Manually pause a running debug session.

evaluate_expression

Evaluate expressions in the current debug context to inspect values and state.

debug_session_state

Query the current state of the active debug session and inspect session details.

processes_overview

Retrieve an overview of all managed debug processes and their statuses.