Docs: npx-based server configs fail on Windows without cmd /c wrapper

[mrjuul]

Problem

All official MCP server READMEs recommend config like:

{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", ...] }

This silently fails on Windows because npx is installed as npx.cmd (a batch script shim), and child_process.spawn() — used by Claude Desktop and Claude Code — cannot execute .cmd files directly.

Expected Behavior

Server READMEs and config examples should include a Windows note, e.g.:

// macOS / Linux
{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", ...] }

// Windows
{ "command": "cmd", "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", ...] }

Affected Servers

Any server installed via npx, including at minimum:

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-gdrive

Root Cause

On Windows, npm installs npx as npx.cmd. Node.js child_process.spawn() cannot execute .cmd files unless shell: true is passed (which MCP clients don't do). The cmd /c wrapper runs the batch script through the Windows command interpreter.

This is a longstanding Node.js-on-Windows issue, not specific to MCP — but since MCP configs are copy-pasted from READMEs, Windows users hit it immediately.

Suggestion

1. Add a "Windows" note to server READMEs showing the cmd /c wrapper
2. Consider adding a note to the MCP SDK docs about this platform difference

Environment

• Windows 11
• Claude Desktop + Claude Code (/doctor warns about this)
• Node.js with npx

Workaround

Change config from "command": "npx" to "command": "cmd" with ["/c", "npx", ...] in args.

[Ankadev-eng]

Additional Windows-specific findings

Confirming this issue on Windows 11 with Claude Desktop. Beyond the cmd /c fix, here are additional findings that may help other Windows users:

Log file location (not documented anywhere for Windows)

Official docs only mention macOS (~/Library/Logs/Claude/). On Windows:

%APPDATA%\Claude\logs\mcp-server-filesystem.log
%APPDATA%\Claude\logs\mcp-server-<servername>.log

To follow logs in real-time (equivalent of tail -f on macOS):

Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50

Two log files / "false disconnect" confusion

After applying config changes, Claude Desktop may show a persistent "Server disconnected" warning that confuses users. This is caused by a stale log entry from a previous session, not the current connection.

The logs contain two separate entries:

• [Filesystem] (capital F) — an older instance, may show transport closed unexpectedly
• [filesystem] (lowercase f) — the current active connection

Only the lowercase entry reflects actual current state. If tools are listed and responding, the server is connected despite the warning.

JSON syntax trap with preferences block

Claude Desktop's claude_desktop_config.json may contain a preferences block managed by the app. When manually editing mcpServers, it's easy to introduce a syntax error by placing a closing } before preferences:

// BROKEN — extra closing brace before preferences
{
  "mcpServers": { ... },
  "globalShortcut": "CommandOrControl+Shift+."
}             ← closes root object too early
  },
  "preferences": { ... }   ← now orphaned, JSON invalid

// CORRECT
{
  "mcpServers": { ... },
  "globalShortcut": "CommandOrControl+Shift+.",   ← comma here
  "preferences": { ... }
}

The app silently fails to load the config when this happens, with no visible error.

Environment

• Windows 11, Claude Desktop latest
• Node.js 22, npm/npx via C:\Users\<user>\AppData\Roaming\npm\
• @modelcontextprotocol/server-filesystem + Desktop Commander MCP

Hope this helps other Windows users hitting the same issues. Supporting #3473 for merge.

[Ishannaik]

Fix confirmed: absolute paths bypass the .cmd shim problem entirely

Ran into this exact issue on Windows 11 + nvm-windows with chrome-devtools-mcp and shadcn MCPs — both npx-based, both silently failing with ✗ Failed to connect in Claude Code.

The .cmd shim problem compounds with nvm-windows: even wrapping with cmd /c npx doesn't reliably work because the subprocess doesn't inherit nvm's PATH environment, so npx can resolve to the wrong Node binary or hang silently.

What works: global install + absolute paths

npm install -g chrome-devtools-mcp@latest

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "C:\nvm4w\nodejs\node.exe",
      "args": [
        "C:\Users\<YOU>\AppData\Roaming\npm\node_modules\chrome-devtools-mcp\build\src\bin\chrome-devtools-mcp.js",
        "--isolated"
      ]
    }
  }
}

Find your paths with:

where node    # → C:\nvm4w\nodejs\node.exe  (nvm-windows symlink, auto-updates on `nvm use`)
npm root -g   # → C:\Users\<YOU>\AppData\Roaming\npm\node_modules

Quick diagnostic

If claude mcp list shows all .exe-based MCPs working but all npx-based ones failing — this is the cause.

Full writeup with manual handshake verification: ChromeDevTools/chrome-devtools-mcp#182 (this comment)

[khalidsaidi]

A2ABench has an accepted answer for this imported thread.

• Thread: https://a2abench-api.web.app/q/cmn744ub50yinvcxycuy0757g
• Accepted at: 2026-03-26T17:12:33.645Z
• Accepted answer agent: ai village
• Answer preview: "This looks like a real docs/platform-compatibility issue, and the basic report is directionally correct: Windows users are hitting avoidable failures when READMEs show "command": "npx" as if it were portable. The practical fix For Windows, the reporter’s documented workaround is "