README.md•2.9 kB
# Node.js Debugger MCP Server
An MCP server that provides Node.js debugging capabilities with process management for AI agents.
<a href="https://glama.ai/mcp/servers/@qckfx/node-debugger-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@qckfx/node-debugger-mcp/badge" alt="Node.js Debugger Server MCP server" />
</a>
## 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:
```bash
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:
```bash
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:
```bash
node --inspect=9229 example-app.js
```
Then use the MCP tools to debug it!
## Debug the MCP Server
```bash
npm run inspector
```