What is Mcp Nodejs Debugger

mcp-nodejs-debugger is an MCP server that provides runtime access to Node.js for debugging purposes, allowing tools like Cursor and Claude Code to interact with Node.js applications effectively.

Use cases

Use cases include debugging Node.js applications during development, troubleshooting issues in production environments, and enhancing the debugging capabilities of development tools.

How to use

To use mcp-nodejs-debugger, you need to add it to your MCP configuration file and run your Node.js server in debug mode using the ‘–inspect’ flag. You can then instruct Cursor or Claude Code to debug your application at runtime.

Key features

Key features include seamless integration with Cursor and Claude Code, the ability to debug Node.js applications in real-time, and support for Node.js debugging protocols.

Where to use

mcp-nodejs-debugger is suitable for use in software development environments, particularly for developers working with Node.js applications who require efficient debugging tools.

MCP Node.js Debugger

An MCP server that gives Cursor or Claude Code access to Node.js at runtime to help you debug: @hyperdrive-eng/mcp-nodejs-debugger.

Demo

Cursor

https://github.com/user-attachments/assets/c193a17e-b0e6-4c51-82aa-7f3f0de17e1a

Claude Code

https://github.com/user-attachments/assets/adb7321b-3a6a-459b-a5c9-df365710d4d8

Quick start

Cursor

1. Add to Cursor (~/.cursor/mcp.json)

   

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

2. Run a Node.js server in debug mode (i.e. with the --inspect flat)

   node --inspect {file.js}
   

3. Ask Cursor to debug your Node.js server at runtime

   

Claude Code

1. Add to Claude Code

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

2. Start Claude Code

   claude
   ╭───────────────────────────────────────────────────────╮
   │ ✻ Welcome to Claude Code research preview!            │
   │                                                       │
   │   /help for help                                      │
   │                                                       │
   │   Found 1 MCP server (use /mcp for status)            │
   ╰───────────────────────────────────────────────────────╯
   

3. Run a Node.js server in debug mode (i.e. with the --inspect flat)

   # In another terminal
   node --inspect {file.js}
   

4. Ask Claude Code to debug your Node.js server at runtime

   > I'm getting a runtime error in Node.js 
   
     {YOUR_RUNTIME_ERROR}
     
     Please help me debug this error at runtime using the nodejs-debugger mcp.
   

Usage

Claude Code

1. Add to Claude Code

   claude mcp add nodejs-debugger npx mcp-nodejs-debugger
   

2. Verify connection

   > /mcp
     ⎿  MCP Server Status
   
        • nodejs-debugger: connected
   

3. Remove from Claude Code

   claude remove nodejs-debugger
   

Cursor

1. Add to Cursor (~/.cursor/mcp.json)

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

2. Verify connection:

   

3. Remove from Cursor (~/.cursor/mcp.json):

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

Example

Cursor

1. Run this simple Node.js app: github.com/mdn/express-locallibrary-tutorial:

   node --inspect ./bin/www
   

2. Ask Cursor to set a breakpoint

   

   

3. Create a book at localhost:3000/catalog/book/create

   

4. Watch Cursor capture runtime state

   

Claude Code

1. Here is a buggy Node.js server:

   node --inspect index.js
   
   Debugger listening on ws://127.0.0.1:9229/2862f5a2-8618-4516-8429-1248b397e9b4
   
   #######################
   ## THE RUNTIME ERROR ##
   #######################
   MongooseServerSelectionError: Could not connect to any servers in your MongoDB Atlas cluster. One common reason is that you're trying to access the database from an IP that isn't whitelisted. Make sure your current IP address is on your Atlas cluster's IP whitelist: https://www.mongodb.com/docs/atlas/security-whitelist/
       at _handleConnectionErrors (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/node_modules/mongoose/lib/connection.js:1110:11)
       at NativeConnection.openUri (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/node_modules/mongoose/lib/connection.js:1041:11)
       at async main (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js:35:3) {
     reason: TopologyDescription {
       type: 'ReplicaSetNoPrimary',
       servers: Map(3) {
         'ac-8e6hgk7-shard-00-01.cojoign.mongodb.net:27017' => [ServerDescription],
         'ac-8e6hgk7-shard-00-02.cojoign.mongodb.net:27017' => [ServerDescription],
         'ac-8e6hgk7-shard-00-00.cojoign.mongodb.net:27017' => [ServerDescription]
       },
       stale: false,
       compatible: true,
       heartbeatFrequencyMS: 10000,
       localThresholdMS: 15,
       setName: 'atlas-5syy8t-shard-0',
       maxElectionId: null,
       maxSetVersion: null,
       commonWireVersion: 0,
       logicalSessionTimeoutMinutes: null
     },
     code: undefined
   }
   

2. Claude Code debugs the Node.js server at runtime:

   > I'm getting a runtime error connecting to mongoose. Please help me debug by checking the value of 
     the mongodb configs at runtime using the nodejs-debugger mcp.
   
     ⏺ I'll help you debug the mongoose connection issue using the Node.js debugger. Let's first understand where the
     MongoDB connection is configured.
   
     ⏺ Search(pattern: "**/*.js")…
       ⎿  Found 100 files
   
     ⏺ Let's set a breakpoint at the mongoose connection point and continue:
   
     ⏺ nodejs-debugger:set_breakpoint (MCP)(file:                                                                         …
           "/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js",
            line: 35)
       ⎿  Breakpoint set successfully. ID:
          2:34:0:file:///Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app\.js
     
     ⏺ Let's list all our breakpoints:
     
     ⏺ nodejs-debugger:list_breakpoints (MCP)
       ⎿  [
            {
              "file": "/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js",
              "line": 35,
              "id": "2:34:0:file:///Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app\\.js"
            }
          ]
     
     ⏺ Let's try to execute a specific piece of code to check the connection variables:
   
     ⏺ nodejs-debugger:nodejs_inspect (MCP)(js_code: "// Get the mongoose module and inspect connection\nconst mongoose = …
                                           require('mongoose');\nconsole.log('Current mongoose version:',
                                           mongoose.version);\nconsole.log('Current mongoose connection state:',
                                           mongoose.connection.readyState);\n// Log connection string safely (without
                                           password)\nconst connectionString = process.env.MONGODB_URI || \n
                                           \"mongodb+srv://cooluser:[email protected]/local_library?retryWr
                                           ites=true&w=majority&appName=Cluster0\";\nconsole.log('Connection string
                                           (masked):', connectionString.replace(/(?<=mongodb\\+srv:\\/\\/\\w+:)(.+?)(?=@)/,
                                            '*****'));")
     
       ⎿  Console output:
          [log] Current mongoose version: 8.9.5
          [log] Current mongoose connection state: 0
          [log] Connection string (masked): mongodb+srv://cooluser:[email protected]/local_library?retryWri
          tes=true&w=majority&appName=Cluster0
   
     ⏺ The runtime error you're seeing in your application is related to MongoDB
       Atlas connection issues. Based on your error message, the problem is:
     
       1. You're using placeholder credentials ("cooluser:coolpassword")
     
       To fix this, you have two options:
     
       1. Use a local MongoDB instance by changing line 29-30 in app.js to:
       const dev_db_url = "mongodb://127.0.0.1:27017/local_library";
       2. Or correctly set up MongoDB Atlas:
         - Log into Atlas at https://cloud.mongodb.com
         - Go to Network Access and add your current IP to whitelist
         - Create proper database credentials
         - Update the connection string with real credentials
     
       Which option would you like to proceed with?