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

> Learn how to connect a debugger to Desktop Commander using the --debug flag. Launch with Node.js inspector enabled on port 9229 to attach Chrome DevTools or VS Code before execution.

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

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js), the flag is detected via a simple argument check:

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

```

The same pattern appears in [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

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

```

### Using Local npm Scripts

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

```bash
npm run start:remote -- --debug

```

Alternatively, the [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) includes a convenience shortcut that encapsulates this behavior:

```bash
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`](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,
  "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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) or [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) and [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.