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

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

Add a "Windows" note to server READMEs showing the cmd /c wrapper
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.

docs(filesystem): add Windows npx cmd /c wrapper note

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.

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)

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 "

Confirming the mechanism, because it explains why this appeared "suddenly" for a lot of people: Node stopped letting spawn() run .cmd/.bat shims directly as part of the Windows batch-file argument-injection hardening, so anything that resolves to npx.cmd needs either shell: true or an explicit interpreter. MCP clients do neither, hence the silent failure.

Three shapes that work, in rough order of robustness:

command: "cmd", args: ["/c", "npx", "-y", ...] - the wrapper in the issue.
Skip the shim entirely: point command at the absolute node.exe and args at the server's entry file. No .cmd anywhere, so quoting and PATH both stop mattering.
If you keep the wrapper, remember that cmd /c re-parses the command line: any argument containing spaces, &, ^ or quotes needs its own escaping layer. That is a common second-order failure once people add the wrapper and it still fails on paths with spaces.

Happy to open a PR adding a Windows note to the READMEs if the maintainers want the docs changed rather than just the issue triaged.

fix(mcp): write a command Windows can actually spawn (ALI-1135) (#314)

Closing: this is available in the v2 release.

Thank you for the suggestion, and apologies for the long wait for a response.

The reference servers were rebuilt for the 2026-07-28 MCP specification (#4857) and released as v2 (2.0.0 on npm for the TypeScript servers, 2026.10.19 on PyPI for the Python servers), and what this asks for is covered there. The root README and each npx-based server README now show the cmd /c wrapper for Windows. This is happening as part of the backlog triage in #4875.

If the v2 behavior doesn't meet the need you had in mind, please open a fresh issue describing what's still missing; see CONTRIBUTING.md.

Navigation Menu

Repository navigation

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

Problem

Expected Behavior

Affected Servers

Root Cause

Suggestion

Environment

Workaround

Additional Windows-specific findings

Log file location (not documented anywhere for Windows)

Two log files / "false disconnect" confusion

JSON syntax trap with `preferences` block

Environment

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

What works: global install + absolute paths

Quick diagnostic

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Problem

Expected Behavior

Affected Servers

Root Cause

Suggestion

Environment

Workaround

Activity

Ankadev-eng commented on Mar 19, 2026

Additional Windows-specific findings

Log file location (not documented anywhere for Windows)

Two log files / "false disconnect" confusion

JSON syntax trap with preferences block

Environment

Ishannaik commented on Mar 26, 2026

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

What works: global install + absolute paths

Quick diagnostic

khalidsaidi commented on Mar 26, 2026

youlemei2022-web commented on Sep 20, 2026

cliffhall commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

JSON syntax trap with `preferences` block

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