# How to Debug the Desktop Commander MCP Server Using Node.js Inspector (Chrome or VS Code)

> Debug the Desktop Commander MCP server efficiently using Node.js inspector with Chrome or VS Code. Learn to attach to port 9229 and step through code.

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

---

**Run the setup with the `--debug` flag to inject `NODE_OPTIONS="--inspect-brk=9229"` into the server configuration, then attach Chrome DevTools or VS Code to port 9229 to step through the Desktop Commander MCP server code.**

The Desktop Commander MCP server is a Node.js application that provides file system and terminal tools for Claude Desktop. When troubleshooting complex tool executions or server initialization issues, you can **debug the MCP server using Node.js inspector** capabilities to set breakpoints and inspect variables in real time. The repository provides a built-in debug mode that configures the server to pause on startup and wait for a debugger to attach.

## How Debug Mode Works in DesktopCommanderMCP

The debugging architecture relies on the Node.js inspector protocol, which implements the Chrome DevTools Protocol (CDP). When enabled, the server process stops before executing any code, exposing port 9229 for debugger attachment.

### The Setup Script Configuration

In [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js), the `isDebugMode()` function detects when you pass the `--debug` flag. Lines 760-795 generate a special server configuration that injects `NODE_OPTIONS="--inspect-brk=9229"` along with `DEBUG="*"`. This configuration is written to Claude's [`claude_desktop_config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/claude_desktop_config.json).

The `--inspect-brk` flag is critical because it forces the Node process to pause on the first line of code, ensuring you can debug server initialization logic before the MCP tools are registered.

### Why NODE_OPTIONS Is Used

The setup script uses the `NODE_OPTIONS` environment variable rather than command-line arguments because the server is launched via `npx`. According to the source code at `wonderwhy-er/DesktopCommanderMCP`, this approach works across Windows and Unix-like platforms, ensuring the inspector flag is passed correctly regardless of how the MCP client spawns the process.

## Method 1: Install the Server in Debug Mode

To enable debugging for the Claude Desktop integration, run the setup command with the debug flag:

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

```

This command modifies your local Claude configuration to include the inspector environment variables. The next time Claude Desktop starts the MCP server, it will pause immediately and wait for a debugger to connect on port 9229.

## Method 2: Debug with Chrome DevTools

Once the server is running in debug mode, you can connect using Chrome's built-in Node.js debugger:

1. Open Chrome and navigate to `chrome://inspect`.

2. Under **Remote Target**, locate the `desktop-commander` process listening on port 9229.

3. Click **Open dedicated DevTools for Node** to launch the debugger.

4. The process will be paused at the first line of [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js). Click **Resume** to continue execution, or set breakpoints in the Sources panel to pause at specific functions.

Chrome DevTools provides full debugging capabilities including call stack inspection, variable evaluation, and console access to the running MCP server context.

## Method 3: Attach with VS Code

For integrated debugging within your development environment, create a launch configuration in [`.vscode/launch.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.vscode/launch.json):

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

```

With the server running in debug mode, press **F5** in VS Code to attach the debugger. You can then set breakpoints in `src/` files, step through asynchronous tool handlers, and inspect variables during MCP request execution.

## Method 4: Direct Debug Script (Development)

If you are developing the server locally without Claude Desktop, use the convenience script defined in [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) (lines 41-43):

```bash
npm run start:debug

```

This command executes `node --inspect-brk=9229 dist/index.js` directly, starting the compiled server with the inspector enabled. This is useful for testing changes to the codebase without reinstalling the MCP configuration in Claude.

## Summary

- **Enable debug mode** by passing `--debug` to the setup script, which configures `NODE_OPTIONS="--inspect-brk=9229"` in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) lines 760-795.
- **Use Chrome** by visiting `chrome://inspect` and opening the dedicated DevTools for the Node process on port 9229.
- **Use VS Code** by creating an attach configuration in [`.vscode/launch.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.vscode/launch.json) that connects to port 9229.
- **Develop locally** using `npm run start:debug` as defined in [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) to start the server with the inspector immediately.
- **Key files** include [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) for configuration injection, [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js) as the debug entry point, and [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) for the debug script definition.

## Frequently Asked Questions

### What port does the Desktop Commander MCP debugger use?

The debugger uses **port 9229** by default. This is configured in [`setup-claude-server.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/setup-claude-server.js) when the `--debug` flag is passed, setting `NODE_OPTIONS="--inspect-brk=9229"`. You can modify this port in the generated Claude configuration if 9229 is already in use on your system.

### Why does the server pause on startup when debugging?

The server pauses because the setup script injects `--inspect-brk` (break) rather than `--inspect`. This ensures the process stops before executing any user code, allowing you to set breakpoints in the initialization logic of [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js) and catch errors that occur during server startup.

### Can I debug the server without installing it in Claude Desktop?

Yes. If you are working on the source code directly, use the `npm run start:debug` command defined in [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) lines 41-43. This starts the compiled server with the Node.js inspector enabled without modifying Claude's configuration files, making it ideal for development and testing.

### Where is the debug configuration stored?

When you run `npx @wonderwhy-er/desktop-commander@latest setup --debug`, the configuration is stored in Claude Desktop's MCP configuration file (typically [`claude_desktop_config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/claude_desktop_config.json) on your system). The generated entry includes the `NODE_OPTIONS` and `DEBUG` environment variables that enable the inspector protocol.