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

When you pass the --debug flag to Desktop Commander, the startup scripts inject --inspect-brk=9229 into the Node.js runtime, pause execution on the first line of user code, and activate verbose console.debug logging so you can attach a debugger on port 9229.

Desktop Commander is a Model Context Protocol (MCP) server that exposes terminal and file system operations to AI assistants. According to the wonderwhy-er/DesktopCommanderMCP source code, the application supports a dedicated debug mode that leverages the Node.js inspector protocol combined with enhanced logging output. Understanding how the --debug flag modifies the startup sequence allows developers to set breakpoints, inspect variables, and trace execution flow in real time.

How the --debug Flag Activates the Node.js Inspector

When you append --debug to the command line, Desktop Commander triggers two distinct mechanisms: Node Inspector injection and verbose logging activation.

Inspector Injection via setup-claude-server.js

In setup-claude-server.js (lines 761–808), the setup script detects the --debug argument and injects the Node.js inspector options into the environment. Specifically, it sets NODE_OPTIONS="--inspect-brk=9229 …", which instructs the Node.js runtime to start the debugging server and pause execution before running user code.

This mechanism ensures that the process halts at the first line of dist/index.js, allowing you to attach a debugger before any initialization logic executes.

Verbose Logging in remote.ts

Simultaneously, the src/npm-scripts/remote.ts file (lines 7–13) scans the command line for the --debug flag. When detected, it sets an internal verbose variable to true, which enables additional console.debug statements throughout the application. These debug logs provide granular visibility into the server's internal state, including session persistence and command execution details.

Starting Desktop Commander in Debug Mode

You can initiate debug mode using either the published npm package or the local development environment.

Method 1: Using the Published Installer

Run the setup command with the debug flag to start the server with inspector support:

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

This command executes setup-claude-server.js, which configures the environment variables and launches the server with --inspect-brk=9229 active.

Method 2: Using the Local npm Script

If you are working from the cloned repository, use the dedicated npm script defined in package.json (line 41):

npm run start:debug

This script launches the built server at dist/index.js with the Node.js inspector already attached and waiting on port 9229.

Attaching Your Debugger to Port 9229

Because the --inspect-brk flag pauses execution immediately, you must attach a debugger client to resume and step through the code.

Attaching with VS Code

Create a .vscode/launch.json file in your project root with the following configuration:

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

After starting Desktop Commander with --debug, press F5 in VS Code to attach the debugger. The process will resume execution, and you can set breakpoints in src/npm-scripts/remote.ts or other source files.

Attaching with Chrome DevTools

1. Open Google Chrome and navigate to chrome://inspect.
2. Click Open dedicated DevTools for Node.
3. Look for the Desktop Commander process in the connection list.
4. Click inspect to open the debugger.

The DevTools interface provides full access to breakpoints, call stacks, and variable inspection for the running MCP server.

What Happens During Debug Execution

Once attached, the debugging session provides several capabilities:

• Breakpoint debugging: Set breakpoints in src/npm-scripts/remote.ts or dist/index.js to pause on specific lines.
• Live variable inspection: Inspect the verbose flag and other runtime variables in real time.
• Debug console output: View the additional console.debug logs that are suppressed in normal mode, giving you visibility into the server's command processing and session management.
• Automatic restart: If configured in your debugger (e.g., VS Code's restart: true), the debugger will reattach when the process restarts.

Summary

• The --debug flag in Desktop Commander triggers Node Inspector injection via setup-claude-server.js, setting NODE_OPTIONS="--inspect-brk=9229".
• Verbose logging is activated in src/npm-scripts/remote.ts (lines 7–13), enabling console.debug output throughout the application.
• You can start debug mode using npx @wonderwhy-er/desktop-commander@latest setup --debug or npm run start:debug from the repository.
• The inspector pauses execution on the first line of code, waiting for attachment on port 9229.
• Attach using VS Code with an "attach" configuration or Chrome DevTools via chrome://inspect.

Frequently Asked Questions

What port does Desktop Commander use for debugging?

Desktop Commander uses port 9229 for the Node.js inspector. This is hardcoded in setup-claude-server.js (lines 761–808) through the --inspect-brk=9229 flag injected into NODE_OPTIONS. Ensure this port is available before starting the debug session.

Can I use VS Code to debug Desktop Commander?

Yes. Configure a Node.js "attach" request in .vscode/launch.json targeting port 9229. Start Desktop Commander with the --debug flag, then launch the VS Code debugger. The configuration should include "restart": true to handle automatic reattachment during server restarts.

What is the difference between start:debug and the --debug flag?

The npm run start:debug command (defined in package.json) is a convenience script for local development that launches the built server with inspector options. The setup --debug command (handled by setup-claude-server.js) is the primary entry point for end users installing via npx, which configures the environment and injects the same inspector flags before spawning the process.

How do I know if debug mode is enabled?

When debug mode is active, you will see two indicators: the process will output a message indicating that the inspector is listening on port 9229, and you will observe additional console.debug logs in the terminal output. These logs are generated by the verbose flag detection logic in src/npm-scripts/remote.ts and provide detailed operational metadata not visible in standard execution.

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