Node.js Debugger MCP server for AI agents

This Node.js Debugger is an MCP server that enables Cursor or Claude Code to connect to running Node.js applications for real-time debugging assistance. It allows AI assistants to inspect, manipulate, and debug your code during execution.

Installation

For Cursor

Add the MCP server to Cursor by editing your configuration file:

{
  "mcpServers": {
  "nodejs-debugger": {
     "command": "npx",
      "args": ["@hyperdrive-eng/mcp-nodejs-debugger"]
    }
  }
}

The configuration file is located at ~/.cursor/mcp.json.

Verify the connection in Cursor settings.
To remove the server, simply delete its entry from the mcp.json file.

For Claude Code

Add the MCP server using the command line:

claude mcp add nodejs-debugger npx @hyperdrive-eng/mcp-nodejs-debugger

Verify the connection:

> /mcp
  ⎿  MCP Server Status

     • nodejs-debugger: connected

To remove the server:
```
claude remove nodejs-debugger
```

Usage Guide

Basic Workflow

Run your Node.js application with the debug flag:
```
node --inspect your-file.js
```
Interact with your AI assistant to debug the application:
- For Cursor: Ask it to debug your Node.js application or set breakpoints
- For Claude Code: Request debugging help with a message like "Please help me debug this error at runtime using the nodejs-debugger mcp"

Example: Setting Breakpoints

In Cursor

Start your Node.js app in debug mode:
```
node --inspect ./bin/www
```
Ask Cursor to set a breakpoint at a specific location in your code
Interact with your app to trigger the breakpoint
Cursor will capture the runtime state and help you analyze the issue

In Claude Code

Start your Node.js app in debug mode:
```
node --inspect index.js
```

Ask Claude Code to help debug an error:

I'm getting a runtime error in Node.js. 
[YOUR_ERROR_DETAILS]
Please help me debug this error at runtime using the nodejs-debugger mcp.

Claude Code will:
- Set breakpoints in relevant code areas
- Execute code to examine variables and state
- Provide analysis and suggested fixes

Advanced Features

Runtime Code Inspection

You can ask the AI to execute specific code to examine the application state. For example:

Can you check the current value of the database connection string?

The AI will use the debugger to inspect variables and return the information to help diagnose issues.

Breakpoint Management

Set, list, and remove breakpoints during runtime:

"Set a breakpoint at line 35 in app.js"
"What are the current breakpoints?"
"Remove the breakpoint from the connection function"

This allows for interactive debugging as you identify problematic code areas.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.