MCP on Windows: stop fighting with npx

Windows accounts for the majority of MCP install failures posted to Reddit, GitHub, and Discord. The problems are almost always the same: the wrong shell, a broken npx invocation, or a PATH that Claude Desktop cannot see. Here is the complete fix.

Why MCP installs fail on Windows

MCP server configs tell your AI tool to launch a process — something like npx -y @upstash/context7-mcp. On macOS and Linux, that just works. On Windows, it breaks for three predictable reasons:

1. Shell mismatch. VS Code and Cursor launch MCP servers using your configured default terminal profile. If that profile is WSL or Git Bash instead of PowerShell or CMD, the Windows PATH is invisible and npxfails with “command not found.”
2. npx resolution. Claude Desktop and Cursor launch as GUI apps, not from a terminal. GUI apps on Windows inherit a stripped-down PATH that often omits the Node bin folder entirely.
3. Backslash escaping. Windows paths use \, which must be doubled to \\ inside JSON strings. Forgetting this causes silent parse failures.

The fastest fix: cmd wrapper

Instead of calling npx directly, route the call through cmd.exe. This lets Windows resolve npx using its own search logic, which works regardless of how your PATH is configured:

{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@upstash/context7-mcp"]
    }
  }
}

This one change fixes 80% of Windows failures. Replace @upstash/context7-mcp with whatever server you are installing.

If cmd doesn't work: use the full path

Find where npx lives by running where npx in Command Prompt. You will get something like C:\Program Files\nodejs\npx.cmd. Use that path directly:

{
  "mcpServers": {
    "context7": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Note the doubled backslashes — that is required JSON escaping, not a typo.

Fix PATH for all servers at once

You can inject the Node bin directory into the environment for any MCP server using the env field:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my/mcp-server"],
      "env": {
        "PATH": "C:\\Program Files\\nodejs;C:\\Windows\\System32"
      }
    }
  }
}

The clean solution: WSL

If you keep hitting Windows-specific friction, move your MCP servers to WSL. Node, Python, and uvx all work exactly as documented once you are in a Linux environment:

# 1. Install WSL (PowerShell as Administrator)
wsl --install

# 2. Inside WSL: install Node
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 3. In your Claude Desktop config
{
  "mcpServers": {
    "context7": {
      "command": "wsl.exe",
      "args": ["npx", "-y", "@upstash/context7-mcp"]
    }
  }
}

Where is the Claude Desktop config on Windows?

Paste this path directly into Explorer's address bar:

%APPDATA%\Claude\claude_desktop_config.json

After editing, quit and reopen Claude Desktop completely — it doesn't hot-reload config changes.

Error messages decoded

“spawn npx ENOENT” — Claude cannot find npx. Use the cmd /c wrapper or the full path.

“Server not initialized” — The process started but crashed before it responded. Run the same npx command manually in a terminal to see the real error. Most often it is a missing env var (API key).

Config resets after update — Claude Desktop sometimes regenerates its config on update. Run npx mcpbolt to re-apply all your servers from a declarative config in one step.

One-command install with MCPBolt CLI

Instead of manually editing JSON, use the MCPBolt CLI — it works on Windows, detects your installed tools, and writes the correct config for each one:

npx mcpbolt

Paste your server config (any format), select Claude Desktop and Cursor, and MCPBolt writes both configs with the correct Windows paths automatically.

See the full Windows install guide in the docs for more troubleshooting steps, or use the Config Validator to catch issues before they cause problems.