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

> Debug Desktop Commander with Node.js inspector and the --debug flag. Activate inspector on port 9229, pause execution, and enable verbose console logging to find and fix bugs quickly.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

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

```

This command downloads the latest version, executes [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js), and automatically configures the inspector environment.

### Method 2: Direct npm Script (Development)

When working from a cloned repository:

```bash
npm run start:debug

```

The [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) defines this script to launch [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js) with inspector flags already applied.

### Method 3: Manual Node.js Invocation

For custom scenarios or integrated workflows:

```bash
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.vscode/launch.json):

```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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js) startup
- **Tool handlers**: Inspect parameters and return values in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)
- **Session management**: Trace `--persist-session` logic in [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts)
- **NPM script execution**: Monitor [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js)
- **Verbose logging** activates through [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```json
{
  "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.