How to Debug the Desktop Commander MCP Server Using Node.js Inspector (Chrome or VS Code)

Run the setup with the --debug flag to inject NODE_OPTIONS="--inspect-brk=9229" into the server configuration, then attach Chrome DevTools or VS Code to port 9229 to step through the Desktop Commander MCP server code.

The Desktop Commander MCP server is a Node.js application that provides file system and terminal tools for Claude Desktop. When troubleshooting complex tool executions or server initialization issues, you can debug the MCP server using Node.js inspector capabilities to set breakpoints and inspect variables in real time. The repository provides a built-in debug mode that configures the server to pause on startup and wait for a debugger to attach.

How Debug Mode Works in DesktopCommanderMCP

The debugging architecture relies on the Node.js inspector protocol, which implements the Chrome DevTools Protocol (CDP). When enabled, the server process stops before executing any code, exposing port 9229 for debugger attachment.

The Setup Script Configuration

In setup-claude-server.js, the isDebugMode() function detects when you pass the --debug flag. Lines 760-795 generate a special server configuration that injects NODE_OPTIONS="--inspect-brk=9229" along with DEBUG="*". This configuration is written to Claude's claude_desktop_config.json.

The --inspect-brk flag is critical because it forces the Node process to pause on the first line of code, ensuring you can debug server initialization logic before the MCP tools are registered.

Why NODE_OPTIONS Is Used

The setup script uses the NODE_OPTIONS environment variable rather than command-line arguments because the server is launched via npx. According to the source code at wonderwhy-er/DesktopCommanderMCP, this approach works across Windows and Unix-like platforms, ensuring the inspector flag is passed correctly regardless of how the MCP client spawns the process.

Method 1: Install the Server in Debug Mode

To enable debugging for the Claude Desktop integration, run the setup command with the debug flag:

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

This command modifies your local Claude configuration to include the inspector environment variables. The next time Claude Desktop starts the MCP server, it will pause immediately and wait for a debugger to connect on port 9229.

Method 2: Debug with Chrome DevTools

Once the server is running in debug mode, you can connect using Chrome's built-in Node.js debugger:

1. Open Chrome and navigate to chrome://inspect.

2. Under Remote Target, locate the desktop-commander process listening on port 9229.

3. Click Open dedicated DevTools for Node to launch the debugger.

4. The process will be paused at the first line of dist/index.js. Click Resume to continue execution, or set breakpoints in the Sources panel to pause at specific functions.

Chrome DevTools provides full debugging capabilities including call stack inspection, variable evaluation, and console access to the running MCP server context.

Method 3: Attach with VS Code

For integrated debugging within your development environment, create a launch configuration in .vscode/launch.json:

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

With the server running in debug mode, press F5 in VS Code to attach the debugger. You can then set breakpoints in src/ files, step through asynchronous tool handlers, and inspect variables during MCP request execution.

Method 4: Direct Debug Script (Development)

If you are developing the server locally without Claude Desktop, use the convenience script defined in package.json (lines 41-43):

npm run start:debug

This command executes node --inspect-brk=9229 dist/index.js directly, starting the compiled server with the inspector enabled. This is useful for testing changes to the codebase without reinstalling the MCP configuration in Claude.

Summary

• Enable debug mode by passing --debug to the setup script, which configures NODE_OPTIONS="--inspect-brk=9229" in setup-claude-server.js lines 760-795.
• Use Chrome by visiting chrome://inspect and opening the dedicated DevTools for the Node process on port 9229.
• Use VS Code by creating an attach configuration in .vscode/launch.json that connects to port 9229.
• Develop locally using npm run start:debug as defined in package.json to start the server with the inspector immediately.
• Key files include setup-claude-server.js for configuration injection, dist/index.js as the debug entry point, and package.json for the debug script definition.

Frequently Asked Questions

What port does the Desktop Commander MCP debugger use?

The debugger uses port 9229 by default. This is configured in setup-claude-server.js when the --debug flag is passed, setting NODE_OPTIONS="--inspect-brk=9229". You can modify this port in the generated Claude configuration if 9229 is already in use on your system.

Why does the server pause on startup when debugging?

The server pauses because the setup script injects --inspect-brk (break) rather than --inspect. This ensures the process stops before executing any user code, allowing you to set breakpoints in the initialization logic of dist/index.js and catch errors that occur during server startup.

Can I debug the server without installing it in Claude Desktop?

Yes. If you are working on the source code directly, use the npm run start:debug command defined in package.json lines 41-43. This starts the compiled server with the Node.js inspector enabled without modifying Claude's configuration files, making it ideal for development and testing.

Where is the debug configuration stored?

When you run npx @wonderwhy-er/desktop-commander@latest setup --debug, the configuration is stored in Claude Desktop's MCP configuration file (typically claude_desktop_config.json on your system). The generated entry includes the NODE_OPTIONS and DEBUG environment variables that enable the inspector protocol.

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