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.