How to Connect a Debugger to Desktop Commander Using the `--debug` Flag

Pass the --debug flag to the setup command or remote script to launch Desktop Commander with the Node.js inspector enabled on port 9229, allowing you to attach Chrome DevTools or VS Code before execution begins.

Desktop Commander MCP is a Model Context Protocol server that enables Claude Desktop to execute terminal commands and manage files on your local machine. When you need to troubleshoot startup issues or step through initialization logic, you can connect a debugger with the --debug flag to pause execution immediately and inspect the runtime state.

How the --debug Flag Enables Debugging

The --debug flag triggers a special initialization mode that prepares the Node.js runtime for remote debugging. According to the wonderwhy-er/DesktopCommanderMCP source code, this flag is detected in two primary entry points and activates both verbose logging and the V8 inspector protocol.

Debug Detection Logic

In setup-claude-server.js, the flag is detected via a simple argument check:

const isDebug = process.argv.includes('--debug');

The same pattern appears in src/npm-scripts/remote.ts, ensuring consistent behavior whether you are running the local setup script or the remote device connector.

When the flag is present, the code appends --inspect-brk=9229 to the Node.js execution arguments. This launches the inspector on port 9229 and pauses execution on the first line of the script, giving you time to attach your debugger before any application logic runs.

Starting Desktop Commander in Debug Mode

You can activate debug mode using either the npx distribution or a local clone of the repository.

Using npx (Recommended)

Run the setup command with the --debug flag appended:

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

Using Local npm Scripts

If you have cloned the repository, use the remote script command:

npm run start:remote -- --debug

Alternatively, the package.json includes a convenience shortcut that encapsulates this behavior:

npm run setup:debug

All three methods launch the server with the inspector active and waiting for a debugger connection on localhost:9229.

Attaching Your Debugger to Port 9229

Once the server starts in debug mode, you must connect your debugging client to the exposed port. The most common options are Chrome DevTools and VS Code.

Chrome DevTools

1. Open Chrome and navigate to chrome://inspect.
2. Look under "Remote Target" for the Node.js process listening on port 9229.
3. Click Inspect to launch the dedicated DevTools debugger.

The DevTools window provides breakpoints, step-through execution, and console access to the running Desktop Commander process.

VS Code

Create a launch configuration in .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Desktop Commander",
  "port": 9229,
  "restart": true,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "${workspaceFolder}"
}

With the configuration in place:

1. Start the server using one of the debug commands above.
2. Press F5 (or select "Start Debugging" from the Run menu) in VS Code.

VS Code will attach to the paused process, allowing you to set breakpoints in setup-claude-server.js or src/npm-scripts/remote.ts before execution continues.

Debugging Behavior Without the Flag

When you start Desktop Commander without the --debug flag, the source code explicitly overrides console.debug with a no-op function to suppress verbose internal logging. This keeps the standard output clean during normal operation.

With the --debug flag present, the original console.debug implementation remains active, providing detailed logging of setup steps and remote device operations alongside the inspector connection. This dual behavior ensures that production usage remains uncluttered while development and troubleshooting sessions have full visibility into the execution flow.

Summary

• The --debug flag is parsed in setup-claude-server.js and src/npm-scripts/remote.ts using process.argv.includes('--debug').
• When enabled, it appends --inspect-brk=9229 to start the Node.js inspector and pause execution immediately.
• You can start debug mode via npx @wonderwhy-er/desktop-commander@latest setup --debug, npm run start:remote -- --debug, or the npm run setup:debug shortcut.
• Attach Chrome DevTools at chrome://inspect or use VS Code with an "attach" configuration pointing to port 9229.
• Without the flag, console.debug is silenced to maintain clean output.

Frequently Asked Questions

What port does the Desktop Commander debugger use?

The debugger exposes the Node.js inspector on port 9229 via the --inspect-brk=9229 argument. You must configure your debugging client (Chrome DevTools or VS Code) to connect to localhost:9229.

Can I use debug mode with the remote script?

Yes. The src/npm-scripts/remote.ts file supports the same --debug flag detection as the setup script. Run npm run start:remote -- --debug to launch the remote device connector with the inspector enabled.

Why is console output silent without the --debug flag?

As implemented in the DesktopCommanderMCP source code, console.debug is overwritten with an empty function when the flag is absent. This prevents verbose internal logging from cluttering the terminal during normal Claude Desktop operation.

Do I need to restart the debugger if the server restarts?

If you are using VS Code with "restart": true in your launch configuration, the debugger will automatically attempt to reattach when the process restarts. For Chrome DevTools, you must manually click Inspect again if the server process exits and restarts.

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