modelcontextprotocol / modelcontextprotocol/servers
Docs: npx-based server configs fail on Windows without cmd /c wrapper
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 90.5k
- Forks
- 11.7k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 5
Description
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 /cwrapper - Consider adding a note to the MCP SDK docs about this platform difference
Environment
- Windows 11
- Claude Desktop + Claude Code (
/doctorwarns about this) - Node.js with npx
Workaround
Change config from "command": "npx" to "command": "cmd" with ["/c", "npx", ...] in args.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the official server READMEs that show npx-based configurations, especially the filesystem and gdrive server documentation, then review the MCP SDK docs for any configuration guidance. Add clear macOS/Linux and Windows examples using the cmd /c wrapper where relevant. Done means affected READMEs explain the Windows difference and their copy-pasteable configurations work for both platforms.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100