MCP Server Setup on Windows - Complete Configuration Guide

Overview: MCP on Windows

Setting up MCP servers on Windows has some unique challenges compared to macOS and Linux. Path separators, shell differences, and Node.js/Python installation quirks can cause errors that don't appear on other platforms. This guide covers every Windows-specific issue and shows you how to get MCP servers running reliably.

Most MCP servers are designed and tested primarily on macOS and Linux, so Windows users often encounter undocumented issues. The good news is that every issue has a straightforward fix once you know what to look for.

Prerequisites: Node.js and Python on Windows

Installing Node.js

Most MCP servers require Node.js. Install it correctly on Windows:

1. Download the LTS version from nodejs.org (use the Windows Installer .msi, not the .zip)
2. During installation, check the box for "Automatically install necessary tools" - this installs build tools needed by some npm packages
3. Restart your terminal after installation
4. Verify: node --version and npx --version should both return version numbers

Critical: If npx is not found after installing Node.js, the Node.js bin directory is not in your PATH. Add C:\Program Files\nodejs\ to your system PATH environment variable manually.

Installing Python

Python-based MCP servers (like many community servers) need Python 3.10+:

1. Download from python.org - use the Windows installer
2. Check "Add Python to PATH" during installation (this is unchecked by default and causes most Python MCP issues on Windows)
3. Verify: python --version and pip --version

On Windows, the Python command may be python or python3 depending on how it was installed. If MCP server configs reference python3 and you have python, create an alias or modify the server command.

PowerShell vs CMD vs Git Bash

Windows has multiple shells, and MCP clients use different ones by default. This matters because path handling, environment variables, and command syntax differ between shells.

Shell	Path Separator	Env Var Syntax	Used By
PowerShell	\	$env:VAR_NAME	Windows Terminal default
CMD	\	%VAR_NAME%	Legacy apps
Git Bash	/	$VAR_NAME	Git for Windows

MCP clients on Windows typically spawn processes using CMD or PowerShell. This means the command in your MCP config needs to be a Windows-compatible executable. For Node.js-based servers, use npx.cmd instead of npx if you encounter issues:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\you\projects"]
    }
  }
}

npx on Windows - Common Issues

The npx command is the most common way to run MCP servers, but it has several Windows-specific quirks:

ENOENT Error

The most common Windows MCP error is spawn ENOENT. This happens when the client can't find the npx executable. Fixes:

1. Use npx.cmd instead of npx in your config
2. Use the full path: C:\Program Files\nodejs\npx.cmd
3. Verify Node.js is in your system PATH (not just user PATH)

For a comprehensive fix guide, see MCP server spawn ENOENT troubleshooting.

npx Cache Issues

npx caches packages in %LOCALAPPDATA%\npm-cache\_npx. If a server fails after an update, clear the cache:

# PowerShell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

# CMD
rmdir /s /q "%LOCALAPPDATA%\npm-cache\_npx"

Execution Policy

PowerShell's execution policy may block npx scripts. If you see "running scripts is disabled on this system", run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Config File Locations on Windows

Each MCP client stores its configuration in a different location on Windows:

Client	Config Location
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Cursor	.cursor\mcp.json (project root) or global settings
VS Code	.vscode\mcp.json or %APPDATA%\Code\User\settings.json
Windsurf	%APPDATA%\Windsurf\mcp_config.json
Claude Code (CLI)	%USERPROFILE%\.claude\settings.json

To quickly open the config directory, type the path (e.g., %APPDATA%\Claude) directly into Windows File Explorer's address bar. This expands the environment variable and navigates to the folder.

WSL vs Native Windows

You have two options for running MCP servers on Windows: natively on Windows, or inside WSL (Windows Subsystem for Linux). Each has trade-offs:

Aspect	Native Windows	WSL
Setup complexity	Medium (path issues)	Higher (WSL + client bridging)
Compatibility	Some servers have issues	Near-perfect Linux compat
File access	Direct Windows paths	/mnt/c/ paths (slower I/O)
Client integration	Direct (same OS)	Requires wsl.exe bridging
Performance	Native speed	Slight overhead

Recommendation: Start with native Windows. Most MCP servers work fine with npx.cmd. Only switch to WSL if you encounter a server that simply won't run on Windows natively (rare with official servers).

To run a server in WSL from a Windows MCP client, use this pattern:

{
  "mcpServers": {
    "my-server": {
      "command": "wsl.exe",
      "args": ["--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Common Windows-Specific Errors

spawn ENOENT on Windows

The Error: spawn npx ENOENT error is the single most common MCP issue on Windows. It means the system can't find the npx executable. Causes and fixes:

• Use npx.cmd: Windows requires the .cmd extension. Change "command": "npx" to "command": "npx.cmd"
• Use full path: "command": "C:\\Program Files\\nodejs\\npx.cmd"
• Restart after Node.js install: PATH changes require a new terminal session

See our complete ENOENT troubleshooting guide for additional fixes.

Path Separator Issues

Windows uses backslashes (\) for paths, but JSON requires escaping them as double backslashes (\\). A common mistake:

// WRONG - unescaped backslashes break JSON parsing
"args": ["C:\Users\you\projects"]

// CORRECT - escaped backslashes
"args": ["C:\\Users\\you\\projects"]

// ALSO CORRECT - forward slashes work in Node.js on Windows
"args": ["C:/Users/you/projects"]

Tip: Use forward slashes (/) in MCP config paths. Node.js accepts forward slashes on all platforms, so C:/Users/you/projects works perfectly and avoids escaping issues.

Long Path Issues

Windows has a 260-character path limit by default. Deep node_modules directories can exceed this. Enable long paths:

# PowerShell (run as Administrator)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Antivirus Interference

Windows Defender and other antivirus software sometimes quarantine or slow down MCP server processes. If servers start slowly or fail intermittently, add exclusions:

# PowerShell (run as Administrator) - Add Windows Defender exclusions
Add-MpPreference -ExclusionPath "C:\Program Files\nodejs"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\npm-cache"
Add-MpPreference -ExclusionPath "$env:APPDATA\npm"

# Verify exclusions were added
Get-MpPreference | Select-Object -ExpandProperty ExclusionPath

These exclusions prevent real-time scanning of Node.js binaries and npm packages, which can reduce MCP server cold start times from 10-15 seconds to 2-3 seconds.

PATH Debugging on Windows

If MCP commands are not found, debug your PATH systematically. GUI applications like Claude Desktop use the system PATH, not your shell session's PATH:

# PowerShell - Check system PATH (used by GUI apps)
[Environment]::GetEnvironmentVariable("Path", "Machine") -split ";"

# PowerShell - Check user PATH
[Environment]::GetEnvironmentVariable("Path", "User") -split ";"

# Find where npx actually is
Get-Command npx.cmd -ErrorAction SilentlyContinue | Select-Object Source
# Or in CMD:
where npx.cmd

# Add Node.js to system PATH permanently (PowerShell as Admin)
$nodePath = "C:\Program Files\nodejs"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
if ($currentPath -notlike "*$nodePath*") {
    [Environment]::SetEnvironmentVariable("Path", "$currentPath;$nodePath", "Machine")
    Write-Host "Added $nodePath to system PATH. Restart apps to pick up the change."
}

If Node.js is only in your user PATH (not system PATH), Claude Desktop and other GUI MCP clients will not find npx.cmd. Either move it to the system PATH or use absolute paths in your MCP configuration.

WSL2 Guide for MCP Servers

Windows Subsystem for Linux 2 (WSL2) provides a full Linux environment that can run MCP servers with near-perfect Linux compatibility. This is useful when a server requires Linux-only dependencies or when you want to use the same configuration as your Linux teammates.

Setting Up WSL2

# Install WSL2 (PowerShell as Admin)
wsl --install

# After reboot, install Ubuntu (default) or your preferred distro
wsl --install -d Ubuntu

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

# Verify
node --version
npx --version

Running MCP Servers from WSL in a Windows Client

To run an MCP server inside WSL while your MCP client (Claude Desktop, Cursor) runs on Windows, use wsl.exe as the command:

{
  "mcpServers": {
    "filesystem-wsl": {
      "command": "wsl.exe",
      "args": ["--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "python-server-wsl": {
      "command": "wsl.exe",
      "args": ["--", "/home/user/.local/bin/uvx", "my-python-mcp-server"]
    }
  }
}

Important WSL considerations:

• File paths must use Linux format (/home/user/) not Windows format (C:\Users\)
• Accessing Windows files from WSL via /mnt/c/ is significantly slower than using WSL-native paths
• Environment variables set in Windows are not passed to WSL processes by default - use the env field in your MCP config
• WSL must be running before the MCP client tries to start the server. If WSL is not active, the server start will fail with ENOENT

First Server Setup Walkthrough

If this is your first time setting up MCP on Windows, follow this exact sequence:

1. Install Node.js LTS from nodejs.org (Windows Installer .msi)
2. Open a new PowerShell or CMD window
3. Verify: npx.cmd --version (should print a version number)
4. Find your client's config file (see locations table above)
5. Add one simple server to test:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/you/Documents"]
    }
  }
}

6. Restart your MCP client
7. Verify the server is connected (check for filesystem tools)
8. Add more servers one at a time, testing each before adding the next

For your first complete MCP server project, see our first MCP server tutorial.

PowerShell vs CMD for MCP Development

When debugging MCP servers on Windows, you will frequently use the terminal. Here is a detailed comparison of PowerShell and CMD for common MCP tasks:

Task	PowerShell	CMD
Find npx location	Get-Command npx.cmd	where npx.cmd
Check Node version	node --version	node --version
View PATH	$env:PATH -split ";"	echo %PATH%
Set env variable	$env:GITHUB_TOKEN="ghp_xx"	set GITHUB_TOKEN=ghp_xx
Check port usage	Get-NetTCPConnection -LocalPort 3000	netstat -ano | findstr :3000
Kill process by PID	Stop-Process -Id 12345	taskkill /PID 12345 /F
Open config directory	explorer $env:APPDATA\Claude	explorer %APPDATA%\Claude
Clear npx cache	Remove-Item -Recurse "$env:LOCALAPPDATA\npm-cache\_npx"	rmdir /s /q "%LOCALAPPDATA%\npm-cache\_npx"
Validate JSON config	Get-Content config.json | ConvertFrom-Json	node -e "require('./config.json')"

Recommendation: Use PowerShell for MCP debugging. It has better error messages, supports structured data output, and handles paths more consistently than CMD. Windows Terminal with PowerShell is the ideal setup for MCP development on Windows.

Common Windows Environment Pitfalls

Beyond the errors covered above, here are additional Windows-specific issues that catch MCP users:

• OneDrive path conflicts: If your Documents folder is synced to OneDrive, the actual path might be C:\Users\you\OneDrive\Documents instead of C:\Users\you\Documents. Verify the actual path before using it in MCP configs.
• User profiles with spaces: If your Windows username contains spaces (like "John Doe"), the user profile path will too. This rarely causes issues in JSON configs since paths are quoted, but can cause problems in wrapper scripts.
• Windows S Mode: Windows in S Mode only allows apps from the Microsoft Store. Node.js and Python installed from their official websites will not work. Disable S Mode first, or install Node.js from the Microsoft Store.
• 32-bit vs 64-bit Node.js: Always install the 64-bit version of Node.js on modern Windows. The 32-bit version may have compatibility issues with some npm packages used by MCP servers.
• Corporate group policies: Some corporate Windows machines restrict script execution, process spawning, or network access. If you encounter "Access Denied" or execution policy errors, contact your IT department about MCP server requirements.

For environment variable configuration on Windows, see our environment variables guide. For running multiple servers, see the multiple server configuration guide.