How to Debug Desktop Commander with Node.js Inspector Using the `--debug` Flag

Supply the --debug flag when starting Desktop Commander to activate the Node.js inspector on port 9229, pause execution on launch, and enable verbose console.debug logging.

Debugging a Model Context Protocol (MCP) server like Desktop Commander requires attaching a debugger to a running Node.js process. The repository provides a built-in --debug flag that automates inspector configuration, making it straightforward to step through code, inspect variables, and diagnose issues. This guide explains how the debug mode works, how to enable it through multiple entry points, and how to connect your preferred debugging tool.

How the --debug Flag Works

Desktop Commander's debug system operates through two coordinated mechanisms controlled by a single flag.

Node.js Inspector Injection

When --debug is detected, the setup script in setup-claude-server.js (lines 761-808) injects NODE_OPTIONS="--inspect-brk=9229" into the environment before spawning the server process. The --inspect-brk flag:

• Starts the Node.js inspector on the default debugging port 9229
• Pauses execution at the first line of user code, ensuring you can attach before any logic runs

This happens automatically whether you run npx @wonderwhy-er/desktop-commander@latest setup --debug or use the npm script directly.

Verbose Logging Activation

The CLI argument parser in src/npm-scripts/remote.ts (lines 7-13) sets a verbose variable when --debug is present. This variable gates additional console.debug statements throughout the remote script, providing granular visibility into:

• Server startup sequence
• Tool execution flow
• Session persistence operations

Methods to Start Debug Mode

Method 1: Using the Published Installer (Recommended)

The simplest approach for most users—no repository clone required:

npx @wonderwhy-er/desktop-commander@latest setup --debug

This command downloads the latest version, executes setup-claude-server.js, and automatically configures the inspector environment.

Method 2: Direct npm Script (Development)

When working from a cloned repository:

npm run start:debug

The package.json defines this script to launch dist/index.js with inspector flags already applied.

Method 3: Manual Node.js Invocation

For custom scenarios or integrated workflows:

NODE_OPTIONS="--inspect-brk=9229" node dist/index.js

This bypasses the helper scripts while achieving identical inspector behavior.

Attaching Your Debugger

Once the process starts with --debug, Node.js halts immediately and waits for a debugger connection on port 9229.

VS Code Configuration

Create or update .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Desktop Commander",
  "port": 9229,
  "restart": true,
  "skipFiles": ["<node_internals>/**"]
}

With the server running in debug mode, press F5 in VS Code to attach. The restart: true setting automatically reattaches if the process restarts.

Chrome DevTools

1. Open Chrome and navigate to chrome://inspect
2. Click "Open dedicated DevTools for Node"
3. Locate "Desktop Commander" in the remote target list and click inspect

The DevTools interface provides full breakpoint support, call stack inspection, and live console access.

What You Can Debug

With the inspector attached and verbose logging enabled:

• Server initialization: Step through dist/index.js startup
• Tool handlers: Inspect parameters and return values in src/server.ts
• Session management: Trace --persist-session logic in src/npm-scripts/remote.ts
• NPM script execution: Monitor setup-claude-server.js orchestration

The console.debug statements only appear when --debug is active, so production logs remain clean while development output stays comprehensive.

Summary

• The --debug flag triggers inspector injection via NODE_OPTIONS="--inspect-brk=9229" in setup-claude-server.js
• Verbose logging activates through src/npm-scripts/remote.ts when the flag is detected
• Three entry points support debug mode: npx installer, npm run start:debug, or manual NODE_OPTIONS
• The process pauses on launch, requiring debugger attachment before continuing
• VS Code and Chrome DevTools both connect to port 9229 for full debugging capabilities

Frequently Asked Questions

What port does the Desktop Commander debugger use?

The inspector binds to port 9229 by default. This is hardcoded in setup-claude-server.js (line ~761) through the --inspect-brk=9229 flag. If this port is occupied, Node.js will fail to start—specify an alternative with --inspect-brk=0 for a random available port, then check the console output.

Why does the process appear to hang when I use --debug?

This is expected behavior. The --inspect-brk flag intentionally pauses execution at the first line until a debugger attaches. The process is not frozen—it's waiting. Connect VS Code or Chrome DevTools to port 9229 to resume and begin debugging.

Can I use --debug with Claude Desktop's MCP configuration?

Yes. Add --debug to the args array in your Claude Desktop MCP settings:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["@wonderwhy-er/desktop-commander@latest", "setup", "--debug"]
    }
  }
}

Claude Desktop will launch the server in debug mode; attach your debugger before triggering any tools.

Does --debug affect performance or stability?

The inspector adds minimal overhead, and the initial breakpoint only delays startup until attachment. Verbose logging increases console I/O slightly but does not alter core logic. For production use, simply omit --debug to disable both mechanisms entirely.

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