How to Set Up Node.js Inspector Debugging and Attach a Debugger to Desktop Commander MCP

Pass the --debug flag to Desktop Commander MCP's setup script, which launches the server with --inspect-brk=9229, then attach Chrome DevTools or VS Code to localhost:9229.

Desktop Commander MCP includes a built-in debug mode that automatically configures the Node.js Inspector for you. This guide walks through enabling debug mode, launching the server with inspector breakpoints, and attaching your preferred debugger. All configuration logic resides in setup-claude-server.js from the wonderwhy-er/DesktopCommanderMCP repository.

Enable Debug Mode in the Setup Script

The setup-claude-server.js file generates launch configurations based on how you run the CLI. When debugMode is true, it injects NODE_OPTIONS with --inspect-brk=9229 to pause execution until a debugger attaches.

Debug Configuration for npx Execution

On Windows, running via npx uses a cmd wrapper with inspector flags in the environment:

// setup-claude-server.js#L761-L785
const debugEnv = {
  "NODE_OPTIONS": "--inspect-brk=9229 --trace-warnings --trace-exit",
  "DEBUG": "*"
};
serverConfig = {
  "command": "cmd",
  "args": ["/c", "npx", packageSpec],
  "env": debugEnv
};

Debug Configuration for Local Installation

For direct Node.js execution (Windows or macOS), the inspector flag passes as a command argument:

// setup-claude-server.js#L800-L811
const debugEnv = {
  "NODE_OPTIONS": "--trace-warnings --trace-exit",
  "DEBUG": "*"
};
serverConfig = {
  "command": isWindows ? "node.exe" : "node",
  "args": ["--inspect-brk=9229", indexPath.replace(/\\/g, '\\\\')],
  "env": debugEnv
};

Launch Desktop Commander MCP in Debug Mode

Start the server with the --debug flag. The process will pause immediately (--inspect-brk) and wait for debugger attachment.

# Via npx (cross-platform)

npx desktop-commander-mcp --debug

# From local clone

node dist/index.js --debug

You should see output similar to:

Debugger listening on ws://127.0.0.1:9229/...
For help, see: https://nodejs.org/en/docs/inspector

Attach Your Debugger

Once the server is waiting, connect your debugger to port 9229.

Option 1: Chrome DevTools

1. Open Chrome and navigate to chrome://inspect
2. Click "Open dedicated DevTools for Node"
3. Select the process labeled localhost:9229
4. Click Inspect to open the debugger

Option 2: VS Code

Create or update .vscode/launch.json in your workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Desktop Commander MCP",
      "port": 9229,
      "restart": true,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "${workspaceFolder}"
    }
  ]
}

Then press F5 or select "Attach to Desktop Commander MCP" from the Run and Debug sidebar.

Effective Debugging Techniques

• Set breakpoints in source files under src/, such as src/remote-device/scripts/blocking-offline-update.js
• Use debugger; statements inline for hard-coded pause points
• Leverage DEBUG=* (already enabled in debug mode) for verbose logging output
• Step through async code with --trace-exit and --trace-warnings flags active

Example breakpoint placement:

// src/remote-device/scripts/blocking-offline-update.js
function updateDeviceStatus(device) {
  debugger; // Execution pauses here when attached
  const status = checkConnectivity(device);
  return status;
}

Exit Debug Mode

Run the setup script without --debug or set debugMode to false in your code. The script omits NODE_OPTIONS and inspector arguments, starting the server normally.

Summary

• Debug mode is triggered by the --debug flag in setup-claude-server.js
• Node.js Inspector launches on port 9229 with --inspect-brk to pause startup
• Two attachment methods: Chrome DevTools (chrome://inspect) or VS Code (launch.json attach configuration)
• Key environment variables: NODE_OPTIONS controls inspector flags; DEBUG=* enables verbose logging
• Windows-specific handling: Uses cmd /c wrapper for npx execution, direct node.exe for local runs

Frequently Asked Questions

What port does Desktop Commander MCP use for debugging?

The inspector binds to port 9229 via --inspect-brk=9229, as hardcoded in setup-claude-server.js. This is the default Node.js inspector port; change it by modifying the args array before running the setup script.

Can I debug Desktop Commander MCP without using npx?

Yes. Clone the repository locally and run node dist/index.js --debug. The setup script detects non-npx execution and configures node (or node.exe on Windows) with the inspector flag directly in the args array rather than through NODE_OPTIONS.

Why does debugging on Windows use cmd /c?

The cmd /c wrapper ensures proper environment variable propagation when spawning npx through a child process. The actual Node.js process still runs with the inspector enabled, so debuggers attach transparently to the underlying node instance, not the cmd wrapper.

How do I see debug logs without attaching a debugger?

The debug configuration sets DEBUG="*" and --trace-warnings, so detailed logs print to stderr automatically. You can also add console.log() statements in src/ files—the output appears in your terminal even without an attached debugger.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}