How to Enable Node.js Debugging with the `--debug` Setup Flag in Desktop Commander MCP

Run Desktop Commander MCP setup with npx @wonderwhy-er/desktop-commander@latest setup --debug to activate Node.js inspector, verbose logging, and full debugging capabilities.

Desktop Commander MCP provides a --debug flag for its setup process that launches the Node.js inspector and enables detailed logging. This guide explains how the flag works, where it's implemented in the source code, and how to use it for troubleshooting installation issues or exploring the codebase.

How the --debug Flag Works

The --debug flag triggers a multi-step debugging pipeline across the Desktop Commander MCP codebase. When present, the setup script activates the Node.js inspector, forwards debugging capabilities to child processes, and enables verbose console output.

Detection happens in setup-claude-server.js through a simple process.argv check:

// setup-claude-server.js
function isDebugMode() {
  return process.argv.includes('--debug');
}

Node inspector activation occurs when isDebugMode() returns true. The script then spawns processes with the --inspect argument, opening the Chrome DevTools-compatible debugger on port 9229.

Verbose logging is controlled in src/npm-scripts/remote.ts, where the same flag detection sets a verbose variable:

// src/npm-scripts/remote.ts
const verbose = process.argv.includes('--debug');
// console.debug statements only emit when verbose === true

Running Setup with Debugging Enabled

You have two ways to enable debugging: direct npx execution or the npm script shortcut.

Method 1: Direct npx with --debug

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

This runs the latest published version with full debugging active.

Method 2: Local Development with npm

npm run setup:debug

The package.json defines this convenience script:

{
  "scripts": {
    "setup:debug": "npm install && npm run build && node setup-claude-server.js --debug"
  }
}

Use Method 1 for quick debugging of published releases. Use Method 2 when modifying source code and needing to debug your local changes.

Attaching a Debugger

Once the setup runs with --debug, attach your preferred Node.js debugger:

• Chrome DevTools: Open chrome://inspect and look for the target on port 9229
• VS Code: Create a launch.json configuration with "request": "attach" and "port": 9229
• Other IDEs: Configure an attach request to localhost:9229

With the debugger attached, you can set breakpoints in setup-claude-server.js, step through flag detection logic, inspect the verbose variable in src/npm-scripts/remote.ts, and trace how debugging arguments propagate to spawned child processes.

Source Code Locations

File	Purpose
setup-claude-server.js	Main entry point; parses --debug and spawns Node with --inspect
src/npm-scripts/remote.ts	Utility module; reads flag to toggle verbose logging
package.json	Defines setup:debug npm script

Summary

• The --debug flag activates Node.js inspector mode and verbose logging in Desktop Commander MCP setup.
• Detection occurs via process.argv.includes('--debug') in both setup-claude-server.js and src/npm-scripts/remote.ts.
• Run with npx @wonderwhy-er/desktop-commander@latest setup --debug for published versions or npm run setup:debug for local development.
• Debug port 9229 opens automatically; attach Chrome DevTools, VS Code, or any Node.js inspector client.

Frequently Asked Questions

What does the --debug flag do exactly in Desktop Commander MCP?

The flag performs three functions: it starts the Node.js inspector on port 9229, enables verbose console.debug output throughout the setup process, and forwards debugging capabilities to any spawned child processes.

Can I use --debug with the npx command?

Yes. Run npx @wonderwhy-er/desktop-commander@latest setup --debug to execute the published package with debugging enabled. The flag passes through npx to the underlying setup script.

Where is the --debug flag parsed in the source code?

The flag is parsed in two locations: setup-claude-server.js for inspector activation and src/npm-scripts/remote.ts for verbose logging control. Both use identical process.argv.includes('--debug') checks.

What port does the Node.js debugger use?

The debugger uses the default Node.js inspector port 9229. You can attach Chrome DevTools at chrome://inspect or configure VS Code with "port": 9229 in your attach configuration.

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