modelcontextprotocol / modelcontextprotocol/servers

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

Open
#3,460 4 comments 0 reactions 0 assignees View on GitHub

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

  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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.