mcp-nodejs-debugger

This MCP server exposes a Node.js debugger interface to Cursor and Claude Code, letting you attach to a Node.js process at runtime and inspect or interact with its execution. The server runs via npx and loads the @hyperdrive-eng/mcp-nodejs-debugger tool, which provides commands to set breakpoints, inspect variables, and step through code in a live Node.js environment. To use Cursor or Claude Code, configure the MCP server as nodejs-debugger and initiate a Node.js process with the Node.js inspector enabled. The MCP tooling then communicates with the running Node.js instance to help you debug runtime issues, view the call stack, and inspect variables without directly editing your code. The README examples show how to add the server to your Cursor or Claude Code setup and how to start debugging sessions using the provided debug commands and prompts.

Prerequisites:

• Node.js and npm installed on your machine
• Access to npx (comes with npm)

Installation steps:

1. Verify Node.js and npm installation:

node -v
npm -v

2. No global installation is required for the MCP server since it runs via npx. Ensure you can reach the npm registry:

npm whoami || echo 'Not logged in to npm'

3. In your development environment, add the MCP server to your Cursor or Claude Code configuration using the exact npx command shown in the README:

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

4. Start debugging as documented by Cursor or Claude Code (no additional server setup required beyond enabling Node.js inspector on your target process).

5. Optional: If you prefer a local install for repeated use, you can install the package globally and run the CLI directly, but this is not required for MCP usage.

npm i -g @hyperdrive-eng/mcp-nodejs-debugger
node --inspect your-app.js

Tips and common issues:

• Ensure your Node.js process is started with the inspector enabled (e.g., node --inspect index.js) to allow the MCP debugger to attach.
• If you hit connection issues, verify network access to the MCP backend and that the Node.js inspector URL is reachable from the client.
• The MCP toolset supports setting breakpoints, listing breakpoints, and inspecting runtime state via commands exposed by the nodejs-debugger interface.
• When using Claude Code, you can verify the MCP connection status with the /mcp status command, which helps confirm the nodejs-debugger is connected.
• If you need to pause and inspect a running function, use the MCP-provided breakpoint commands to suspend execution at the desired file and line.
• If you run into environment-specific issues, ensure any required environment variables for your Node.js app (e.g., database URLs, API keys) are properly configured in your runtime environment or through your process manager.