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

> Debug Desktop Commander with the Node.js inspector and --debug flag. Learn to attach a debugger on port 9229 and pause execution for easier troubleshooting in your development workflow.

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

---

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

In [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js), allowing you to attach a debugger before any initialization logic executes.

### Verbose Logging in [`remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/remote.ts)

Simultaneously, the [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

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

```

This command executes [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) (line 41):

```bash
npm run start:debug

```

This script launches the built server at [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.vscode/launch.json) file in your project root with the following configuration:

```json
{
  "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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts) or [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js), setting `NODE_OPTIONS="--inspect-brk=9229"`.
- **Verbose logging** is activated in [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts) and provide detailed operational metadata not visible in standard execution.