From 91eb31b32eaa92f2c7ce9a83e6f98662e6fc5529 Mon Sep 17 00:00:00 2001 From: r266-tech Date: Thu, 5 Mar 2026 04:35:35 +0800 Subject: [PATCH] docs: add Windows npx workaround to server READMEs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On Windows, npx is installed as npx.cmd — a batch file shim that child_process.spawn() cannot execute directly without shell: true. MCP clients (Claude Desktop, Claude Code) do not pass shell: true, so npx-based configs silently fail on Windows. Add a note after each NPX config block explaining the issue and showing the cmd /c workaround for affected servers: - filesystem - memory - sequentialthinking - everything Fixes #3460 --- src/everything/README.md | 34 ++++++++++++++++++++ src/filesystem/README.md | 37 ++++++++++++++++++++++ src/memory/README.md | 54 ++++++++++++++++++++++++++++++++ src/sequentialthinking/README.md | 34 ++++++++++++++++++++ 4 files changed, 159 insertions(+) diff --git a/src/everything/README.md b/src/everything/README.md index 8109e4449f..972b58989b 100644 --- a/src/everything/README.md +++ b/src/everything/README.md @@ -31,6 +31,23 @@ Add to your `claude_desktop_config.json`: } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "everything": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-everything" +> ] +> } +> } +> } +> ``` + ## Usage with VS Code For quick installation, use of of the one-click install buttons below... @@ -62,6 +79,23 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json` } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "servers": { +> "everything": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-everything" +> ] +> } +> } +> } +> ``` + ## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)) ```shell diff --git a/src/filesystem/README.md b/src/filesystem/README.md index bf087a2b25..6e91c90636 100644 --- a/src/filesystem/README.md +++ b/src/filesystem/README.md @@ -250,6 +250,25 @@ Note: all directories must be mounted to `/projects` by default. } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "filesystem": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-filesystem", +> "C:\\Users\\username\\Desktop", +> "C:\\path\\to\\other\\allowed\\dir" +> ] +> } +> } +> } +> ``` + ## Usage with VS Code For quick installation, click the installation buttons below... @@ -308,6 +327,24 @@ Note: all directories must be mounted to `/projects` by default. } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "servers": { +> "filesystem": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-filesystem", +> "${workspaceFolder}" +> ] +> } +> } +> } +> ``` + ## Build Docker build: diff --git a/src/memory/README.md b/src/memory/README.md index dcc8116156..eb2e16d532 100644 --- a/src/memory/README.md +++ b/src/memory/README.md @@ -159,6 +159,23 @@ Add this to your claude_desktop_config.json: } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "memory": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-memory" +> ] +> } +> } +> } +> ``` + #### NPX with custom setting The server can be configured using the following environment variables: @@ -180,6 +197,26 @@ The server can be configured using the following environment variables: } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "memory": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-memory" +> ], +> "env": { +> "MEMORY_FILE_PATH": "C:\\path\\to\\custom\\memory.jsonl" +> } +> } +> } +> } +> ``` + - `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory) # VS Code Installation Instructions @@ -216,6 +253,23 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json` } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "servers": { +> "memory": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-memory" +> ] +> } +> } +> } +> ``` + #### Docker ```json diff --git a/src/sequentialthinking/README.md b/src/sequentialthinking/README.md index 322ded2726..75e6ef832d 100644 --- a/src/sequentialthinking/README.md +++ b/src/sequentialthinking/README.md @@ -59,6 +59,23 @@ Add this to your `claude_desktop_config.json`: } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "sequential-thinking": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-sequential-thinking" +> ] +> } +> } +> } +> ``` + #### docker ```json @@ -114,6 +131,23 @@ For NPX installation: } ``` +> **Windows users:** On Windows, `npx` is a `.cmd` batch file shim that cannot be executed directly by `child_process.spawn()`. Use `cmd /c` as the command instead: +> +> ```json +> { +> "servers": { +> "sequential-thinking": { +> "command": "cmd", +> "args": [ +> "/c", "npx", +> "-y", +> "@modelcontextprotocol/server-sequential-thinking" +> ] +> } +> } +> } +> ``` + For Docker installation: ```json