# How to Set Up Node.js Inspector Debugging and Attach a Debugger to Desktop Commander MCP

> Easily set up Node.js inspector debugging for Desktop Commander MCP. Launch with the debug flag and attach Chrome DevTools or VS Code to localhost:9229 for seamless troubleshooting.

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

---

**Pass the `--debug` flag to Desktop Commander MCP's setup script, which launches the server with `--inspect-brk=9229`, then attach Chrome DevTools or VS Code to localhost:9229.**

Desktop Commander MCP includes a built-in debug mode that automatically configures the Node.js Inspector for you. This guide walks through enabling debug mode, launching the server with inspector breakpoints, and attaching your preferred debugger. All configuration logic resides in **[`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js)** from the [wonderwhy-er/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP) repository.

## Enable Debug Mode in the Setup Script

The **[`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js)** file generates launch configurations based on how you run the CLI. When **`debugMode`** is `true`, it injects `NODE_OPTIONS` with `--inspect-brk=9229` to pause execution until a debugger attaches.

### Debug Configuration for npx Execution

On Windows, running via `npx` uses a `cmd` wrapper with inspector flags in the environment:

```js
// setup-claude-server.js#L761-L785
const debugEnv = {
  "NODE_OPTIONS": "--inspect-brk=9229 --trace-warnings --trace-exit",
  "DEBUG": "*"
};
serverConfig = {
  "command": "cmd",
  "args": ["/c", "npx", packageSpec],
  "env": debugEnv
};

```

### Debug Configuration for Local Installation

For direct Node.js execution (Windows or macOS), the inspector flag passes as a command argument:

```js
// setup-claude-server.js#L800-L811
const debugEnv = {
  "NODE_OPTIONS": "--trace-warnings --trace-exit",
  "DEBUG": "*"
};
serverConfig = {
  "command": isWindows ? "node.exe" : "node",
  "args": ["--inspect-brk=9229", indexPath.replace(/\\/g, '\\\\')],
  "env": debugEnv
};

```

## Launch Desktop Commander MCP in Debug Mode

Start the server with the `--debug` flag. The process will pause immediately (`--inspect-brk`) and wait for debugger attachment.

```bash

# Via npx (cross-platform)

npx desktop-commander-mcp --debug

# From local clone

node dist/index.js --debug

```

You should see output similar to:

```

Debugger listening on ws://127.0.0.1:9229/...
For help, see: https://nodejs.org/en/docs/inspector

```

## Attach Your Debugger

Once the server is waiting, connect your debugger to **port 9229**.

### Option 1: Chrome DevTools

1. Open Chrome and navigate to `chrome://inspect`
2. Click **"Open dedicated DevTools for Node"**
3. Select the process labeled `localhost:9229`
4. Click **Inspect** to open the debugger

### Option 2: VS Code

Create or update [`.vscode/launch.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.vscode/launch.json) in your workspace:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Desktop Commander MCP",
      "port": 9229,
      "restart": true,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "${workspaceFolder}"
    }
  ]
}

```

Then press **F5** or select **"Attach to Desktop Commander MCP"** from the Run and Debug sidebar.

## Effective Debugging Techniques

- **Set breakpoints** in source files under `src/`, such as [`src/remote-device/scripts/blocking-offline-update.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/scripts/blocking-offline-update.js)
- **Use `debugger;` statements** inline for hard-coded pause points
- **Leverage `DEBUG=*`** (already enabled in debug mode) for verbose logging output
- **Step through async code** with `--trace-exit` and `--trace-warnings` flags active

Example breakpoint placement:

```js
// src/remote-device/scripts/blocking-offline-update.js
function updateDeviceStatus(device) {
  debugger; // Execution pauses here when attached
  const status = checkConnectivity(device);
  return status;
}

```

## Exit Debug Mode

Run the setup script without `--debug` or set `debugMode` to `false` in your code. The script omits `NODE_OPTIONS` and inspector arguments, starting the server normally.

## Summary

- **Debug mode** is triggered by the `--debug` flag in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js)
- **Node.js Inspector** launches on port 9229 with `--inspect-brk` to pause startup
- **Two attachment methods**: Chrome DevTools (`chrome://inspect`) or VS Code ([`launch.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/launch.json) attach configuration)
- **Key environment variables**: `NODE_OPTIONS` controls inspector flags; `DEBUG=*` enables verbose logging
- **Windows-specific handling**: Uses `cmd /c` wrapper for `npx` execution, direct `node.exe` for local runs

## Frequently Asked Questions

### What port does Desktop Commander MCP use for debugging?

The inspector binds to **port 9229** via `--inspect-brk=9229`, as hardcoded in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js). This is the default Node.js inspector port; change it by modifying the `args` array before running the setup script.

### Can I debug Desktop Commander MCP without using npx?

Yes. Clone the repository locally and run `node dist/index.js --debug`. The setup script detects non-npx execution and configures `node` (or `node.exe` on Windows) with the inspector flag directly in the `args` array rather than through `NODE_OPTIONS`.

### Why does debugging on Windows use cmd /c?

The `cmd /c` wrapper ensures proper environment variable propagation when spawning `npx` through a child process. The actual Node.js process still runs with the inspector enabled, so debuggers attach transparently to the underlying `node` instance, not the `cmd` wrapper.

### How do I see debug logs without attaching a debugger?

The debug configuration sets `DEBUG="*"` and `--trace-warnings`, so detailed logs print to stderr automatically. You can also add `console.log()` statements in `src/` files—the output appears in your terminal even without an attached debugger.