# How to Enable Node.js Debugging with the `--debug` Setup Flag in Desktop Commander MCP

> Enable Node.js debugging in Desktop Commander MCP using the --debug flag for inspector, verbose logging, and full debugging. Learn how to set it up easily.

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

---

**Run Desktop Commander MCP setup with `npx @wonderwhy-er/desktop-commander@latest setup --debug` to activate Node.js inspector, verbose logging, and full debugging capabilities.**

Desktop Commander MCP provides a `--debug` flag for its setup process that launches the Node.js inspector and enables detailed logging. This guide explains how the flag works, where it's implemented in the source code, and how to use it for troubleshooting installation issues or exploring the codebase.

## How the `--debug` Flag Works

The `--debug` flag triggers a multi-step debugging pipeline across the Desktop Commander MCP codebase. When present, the setup script activates the Node.js inspector, forwards debugging capabilities to child processes, and enables verbose console output.

**Detection** happens in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) through a simple `process.argv` check:

```javascript
// setup-claude-server.js
function isDebugMode() {
  return process.argv.includes('--debug');
}

```

**Node inspector activation** occurs when `isDebugMode()` returns `true`. The script then spawns processes with the `--inspect` argument, opening the Chrome DevTools-compatible debugger on port 9229.

**Verbose logging** is controlled in [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts), where the same flag detection sets a `verbose` variable:

```typescript
// src/npm-scripts/remote.ts
const verbose = process.argv.includes('--debug');
// console.debug statements only emit when verbose === true

```

## Running Setup with Debugging Enabled

You have two ways to enable debugging: direct npx execution or the npm script shortcut.

### Method 1: Direct npx with `--debug`

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

```

This runs the latest published version with full debugging active.

### Method 2: Local Development with npm

```bash
npm run setup:debug

```

The [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) defines this convenience script:

```json
{
  "scripts": {
    "setup:debug": "npm install && npm run build && node setup-claude-server.js --debug"
  }
}

```

**Use Method 1** for quick debugging of published releases. **Use Method 2** when modifying source code and needing to debug your local changes.

## Attaching a Debugger

Once the setup runs with `--debug`, attach your preferred Node.js debugger:

- **Chrome DevTools**: Open `chrome://inspect` and look for the target on port 9229
- **VS Code**: Create a [`launch.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/launch.json) configuration with `"request": "attach"` and `"port": 9229`
- **Other IDEs**: Configure an attach request to `localhost:9229`

With the debugger attached, you can set breakpoints in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js), step through flag detection logic, inspect the `verbose` variable in [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts), and trace how debugging arguments propagate to spawned child processes.

## Source Code Locations

| File | Purpose |
|------|---------|
| [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) | Main entry point; parses `--debug` and spawns Node with `--inspect` |
| [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts) | Utility module; reads flag to toggle verbose logging |
| [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) | Defines `setup:debug` npm script |

## Summary

- **The `--debug` flag** activates Node.js inspector mode and verbose logging in Desktop Commander MCP setup.
- **Detection occurs** via `process.argv.includes('--debug')` in both [`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).
- **Run with** `npx @wonderwhy-er/desktop-commander@latest setup --debug` for published versions or `npm run setup:debug` for local development.
- **Debug port 9229** opens automatically; attach Chrome DevTools, VS Code, or any Node.js inspector client.

## Frequently Asked Questions

### What does the `--debug` flag do exactly in Desktop Commander MCP?

The flag performs three functions: it starts the Node.js inspector on port 9229, enables verbose `console.debug` output throughout the setup process, and forwards debugging capabilities to any spawned child processes.

### Can I use `--debug` with the npx command?

Yes. Run `npx @wonderwhy-er/desktop-commander@latest setup --debug` to execute the published package with debugging enabled. The flag passes through npx to the underlying setup script.

### Where is the `--debug` flag parsed in the source code?

The flag is parsed in two locations: [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) for inspector activation and [`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts) for verbose logging control. Both use identical `process.argv.includes('--debug')` checks.

### What port does the Node.js debugger use?

The debugger uses the default Node.js inspector port 9229. You can attach Chrome DevTools at `chrome://inspect` or configure VS Code with `"port": 9229` in your attach configuration.