MCP on Windows

Windows is the most common source of MCP install failures. Most problems trace back to three root causes: the wrong shell, a broken npx invocation, or a PATH that Claude Desktop cannot see. This page covers all of them.

Root cause 1 — Wrong shell in VS Code / Cursor

When VS Code or Cursor launches an MCP server, it uses the shell configured in your editor. If that shell is zsh (which some setups pick up from WSL), the Windows PATH is not available and npxfails with “command not found.”

Fix: set the default terminal profile

In VS Code / Cursor, open the command palette (Ctrl+Shift+P) and run Terminal: Select Default Profile. Choose Command Prompt or PowerShell — not Git Bash or WSL.

Then restart the editor and try the MCP server again.

Root cause 2 — npx path issues

npx on Windows resolves differently depending on how Node.js was installed. The MCP config needs the full resolved command, not just npx.

Check: find where npx lives

Open Command Prompt and run:

where npx

You will get a path like C:\\Program Files\\nodejs\\npx.cmd.

Fix A — Use cmd as the command

Wrap the npx call through cmd.exe so Windows resolves the path correctly:

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

Fix B — Use the full path to npx

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

Root cause 3 — PATH not visible to Claude Desktop

Claude Desktop launches as a GUI app, not from a terminal. GUI apps on Windows do not inherit the PATH you set in PowerShell or your user environment in the same way. This means node, npx, python, and uvx may all be invisible to Claude even if they work fine in your terminal.

Fix A — Set PATH via the env field

You can inject PATH into the MCP server's environment directly in the config:

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

Fix B — Use the full absolute path to node

{
  "mcpServers": {
    "my-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YourName\\my-mcp-server\\index.js"]
    }
  }
}

The WSL approach (cleanest solution)

If you keep hitting Windows-specific issues, running MCP servers inside WSL (Windows Subsystem for Linux) eliminates them entirely. Node, Python, and all standard Unix tools work exactly as documented.

Step 1 — Install WSL

# Run in PowerShell as Administrator
wsl --install

This installs Ubuntu by default. Restart when prompted.

Step 2 — Install Node inside WSL

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

Step 3 — Reference the WSL binary from Claude Desktop

Claude Desktop on Windows can call WSL executables via the wsl.exe wrapper:

{
  "mcpServers": {
    "context7": {
      "command": "wsl.exe",
      "args": ["npx", "-y", "@upstash/context7-mcp"]
    }
  }
}

Common error messages and fixes

“spawn npx ENOENT”

Claude cannot find npx. Use Fix B above (full path) or the cmd /c wrapper (Fix A).

“Server not initialized”

The server process started but failed before it could respond. Common causes: missing env vars (API keys), a package that failed to download on the first npx run, or a Node version mismatch. Run the npx command manually in a terminal to see the real error.

“Bad Request” on a Streamable HTTP server

Usually a missing or malformed Authorization header. Check that your API key is set and that the header name matches exactly what the provider expects.

Config resets after Claude Desktop updates

Claude Desktop occasionally moves or regenerates claude_desktop_config.json on update. Keep a backup copy and use npx mcpbolt to re-apply your servers in one command.

Quick checklist

1. Run where npx and where node in Command Prompt — note the paths.
2. Use cmd /c npx … or the full npx path in your config.
3. If PATH is the issue, add it to the env block in your config.
4. For VS Code / Cursor: set the default terminal profile to PowerShell or CMD.
5. For a clean slate: switch to WSL and use Linux paths.