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.

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:

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:

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 for your Node.js installation directory and the npx cache (%LOCALAPPDATA%\npm-cache).

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.