Updated May 2026How-to22 min read

Claude Code MCP on Windows — The Complete WSL + Native Setup Guide (2026)

If you’re on Windows and /mcp shows nothing, an MCP server crashes with spawn npx ENOENT, or you just got claude is not recognized from PowerShell — this is the page. We walk both supported paths (WSL2 and native Windows), cite the underlying GitHub issues so you know why each workaround exists, and get you to a working claude mcp list in under fifteen minutes. New to the protocol? Start with our What is MCP primer first.

Editorial illustration: a Windows 11 sky-blue terminal beside a teal WSL Ubuntu terminal, connected by a glowing pipeline of dot-and-dash light, with a subtle MCP gear glyph at the junction, on a midnight navy background.
On this page · 12 sections
  1. TL;DR + which path to pick
  2. Why Windows + MCP is hard
  3. Path A — WSL2 (recommended)
  4. Path B — Native Windows
  5. MCP compatibility table
  6. Cursor / VS Code / Cline on Windows
  7. Antivirus + corporate proxy
  8. Remote MCP + OAuth (the easy mode)
  9. Diagnosing failures
  10. Community signal
  11. FAQ
  12. Sources

TL;DR + which path to pick

  • Most Windows developers should use WSL2. The MCP ecosystem was written against macOS / Linux. You spend zero minutes fighting spawn ENOENT, Windows path quoting, MSIX virtualization, or antivirus quarantine of npx-fetched binaries. The Microsoft one-liner wsl --install ships Ubuntu and is the official Microsoft-supported install path.
  • Use native Windows when you must. Locked-down corporate machines that don’t allow Hyper-V, .NET / PowerShell-only toolchains, projects that live in C:\ and would be slow over the WSL 9P filesystem boundary. Anthropic ships a native claude.exe (PowerShell installer or WinGet), and most stdio MCP servers work on it as long as you wrap npx with cmd /c.
  • Use remote MCP wherever possible. Hosted endpoints (Context7, DeepWiki, Notion, Linear) bypass every Windows-specific bug listed below because there’s no local subprocess to spawn.

The rest of this guide is organized as a sequence: read the failure-mode matrix → pick a path → run the install → pin down which kind of failure you’re seeing. If you’re already past the install step and just need a fix, skip to Diagnosing failures.

Why Windows + MCP is hard

The Model Context Protocol’s most common transport is stdio: the host (Claude Code) spawns a subprocess and talks JSON-RPC over its stdin/stdout pipe. That works cleanly on macOS / Linux because npx, uvx, node, and python are all real binaries on $PATH and the kernel knows how to execve() them. On Windows, four things stack on top of each other to make the same setup fragile.

1. npx is a batch file, not a binary. On Windows, npx ships as npx.cmd in %APPDATA%\npm. Node’s child_process.spawn() doesn’t go through a shell by default, so when Claude Code calls spawn("npx", ...) the OS can’t find an executable named exactly npx and returns ENOENT. The fix — wrap with cmd /c — is the single most-cited workaround in the Anthropic, Cursor, Cline, and Windsurf bug trackers. We’ll cover it explicitly below.

2. MSIX virtualization splits config files. Claude Desktop on Windows ships as an MSIX package. MSIX apps run inside a virtualized filesystem; reads and writes under %APPDATA%\Claude\ get silently redirected to %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\. The “Edit Config” button inside the app uses an Electron API that doesn’t follow the redirect — so the file you edit is not the file the app reads. This is GitHub issue #26073 and it’s why your perfectly-correct claude_desktop_config.json can be entirely ignored.

3. Native stdio MCP loading is still flaky. As of Claude Code 2.1.72, user StingyJack reported in issue #32951 that local stdio MCP servers configured in any of the supported config locations (~/.mcp.json, ~/.claude/settings.json, project .mcp.json) are completely ignored on native Windows but the same configuration works under WSL on the same machine. The bug is open at the time of writing.

4. cmd.exe console windows flash on every spawn. Even when MCP servers do connect on native Windows, the Claude desktop app spawns subprocesses without the windowsHide: true flag. Every MCP server start, every Chrome native-host launch, every internal claude.cmd spawn pops a brief cmd window onto your screen. Tracked in issue #44039.

None of these are reasons to give up on Windows. Theyare reasons to know what’s happening so you don’t spend hours staring at an empty /mcp command. Here’s the canonical bug report from issue #22706 (verbatim, public, dated 2026-02-03):

MCP servers configured in ~/.claude/mcp.json are not being loaded/connected by Claude Code CLI on Windows 11. The MCP server works correctly when called directly via bash, but Claude Code does not recognize or connect to it. /mcp shows empty/nothing. MCP server is not connected. No error messages displayed.

DavidRHerbert (GitHub issue #22706) · Blog

Reported on Windows 11, Node.js v24.4.0, Claude Code 1.1.1520. Status: closed.

Source

Path A — WSL2 (recommended for most)

The TL;DR for this path is four commands, run in this order: wsl --install in elevated PowerShell, then nvm install --lts inside Ubuntu, then curl -fsSL https://claude.ai/install.sh | bash, then claude mcp add for each server. We’ll walk each step.

Step 1 — Install WSL2 + Ubuntu

Open PowerShell as Administrator (right-click Start → “Windows Terminal (Admin)” or “PowerShell (Admin)”) and run:

wsl --install

Per Microsoft’s official install page: “This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux.” Restart when prompted. On first launch you’ll be asked to set a Linux username and password — make these whatever you want; they’re local to the WSL VM.

Verify you’re on WSL2 (not WSL1), because WSL1 lacks the proper Linux kernel and can break some MCP servers:

wsl --list --verbose
# NAME      STATE           VERSION
# Ubuntu    Running         2

If you see VERSION 1, upgrade with wsl --set-version Ubuntu 2. Microsoft’s docs cover the prerequisites for systems where WSL2 is blocked (Hyper-V disabled in BIOS, older Windows builds).

Step 2 — Install Node.js inside WSL

Don’t install Node on the Windows side and try to call it from WSL — that’s the most common path-resolution headache in this whole guide. Install Node inside the Ubuntu VM, where Claude Code will spawn it.nvm is the cleanest option:

# Inside your WSL Ubuntu shell:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# Reload shell so nvm is on PATH:
source ~/.bashrc

# Install Node LTS:
nvm install --lts
nvm use --lts

# Verify:
node --version
npm --version
npx --version

If you prefer the system package, sudo apt install nodejs npm works on Ubuntu 24.04 LTS but ships an older Node and isn’t recommended for MCP servers that pin recent Node features. nvm gives you per-shell Node version control, which matters when one MCP server wants Node 20 and another wants Node 22.

Step 3 — Install Claude Code in WSL

The official installer command from code.claude.com/docs/en/setup for “macOS, Linux, WSL”:

# Inside your WSL Ubuntu shell:
curl -fsSL https://claude.ai/install.sh | bash

# Verify:
claude --version
claude doctor

claude doctor is the most under-used tool in this guide — it surfaces install path conflicts, version mismatches, missing dependencies (ripgrep,libgcc on Alpine), and bad PATH entries. Always run it before opening a bug report.

Per the docs: “Native installations automatically update in the background to keep you on the latest version.” You don’t need to manage upgrades.

Step 4 — Configure your first three MCP servers

The claude mcp add command syntax (per the official MCP docs at code.claude.com/docs/en/mcp):

# Stdio (subprocess) — run a local Node MCP server
claude mcp add <name> -- <command> [args...]

# Stdio with env var
claude mcp add --transport stdio --env API_KEY=YOUR_KEY <name> \
  -- npx -y <package>

# Remote HTTP (the easy mode)
claude mcp add --transport http <name> <url>

# Remote SSE (deprecated but supported)
claude mcp add --transport sse <name> <url>

Three concrete examples that almost every developer wants:

# 1. Filesystem — give Claude access to a directory tree
claude mcp add filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /home/you/projects

# 2. GitHub — official remote endpoint, OAuth-based
claude mcp add --transport http github https://api.githubcopilot.com/mcp

# 3. Context7 — version-pinned docs RAG
claude mcp add --transport http context7 https://mcp.context7.com/mcp

Verify they all loaded:

claude mcp list
# filesystem  stdio    connected
# github      http     connected
# context7    http     connected

If any line shows not connected or the server is missing entirely, jump to Diagnosing failures.

One-line install · Filesystem

Open server page

Install

One-line install · GitHub

Open server page

Install

One-line install · Context7

Open server page

Install

Step 5 — Open your project

The pitfall here is choosing where your code lives. WSL2 exposes the Windows drives at /mnt/c/, but reads and writes across that boundary go through the 9P protocol and are 5–20× slower than native Linux paths. The Microsoft-recommended pattern is to keep your project inside the Linux home directory (~/projects/my-app) and use VS Code’s Remote-WSL extension to edit it. If you must work on a Windows-side path, you can — cd /mnt/c/Users/you/repos/my-app — just expect the slowdown on big git status or npm install runs.

Common WSL pitfalls

  • npx: command not found after install. You exited and re-opened the shell, but nvm hasn’t been sourced. Add export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" to your ~/.bashrc.
  • WSL clock drift breaking OAuth. If your Windows host laptop suspended for several hours, WSL’s clock can drift far enough that OAuth signature verification fails. Run sudo hwclock -s in WSL to resync.
  • Networking issues with hosted MCP servers. WSL2’s default NAT mode sometimes fails on corporate VPNs. Edit %USERPROFILE%\.wslconfig and set networkingMode=mirrored, then run wsl --shutdown.
  • WSL1 instead of WSL2. Older Windows installs default to WSL1, which uses a translation layer instead of a real Linux kernel. Many newer MCP servers rely on epoll or other Linux-only syscalls WSL1 doesn’t expose. Always run on WSL2.

Path B — Native Windows (no WSL)

Anthropic officially supports native Windows. Per the setup docs, the system requirements are: “Windows 10 1809+ or Windows Server 2019+”, with “Bash, Zsh, PowerShell, or CMD” as supported shells. “On native Windows, Git for Windows is recommended; Claude Code falls back to PowerShell when Git Bash is absent.

Step 1 — Install Node.js for Windows

Grab the LTS installer from nodejs.org/en/download — pick the “Windows Installer (.msi)” for x64. Or, with WinGet:

# In PowerShell (no admin needed):
winget install OpenJS.NodeJS.LTS

# Verify after closing and reopening PowerShell:
node --version
npm --version
where npx

where npx is your friend on Windows — it shows you the actual .cmd path npm installed. Expect something like C:\Program Files\nodejs\npx.cmd or C:\Users\you\AppData\Roaming\npm\npx.cmd.

Step 2 — Install Git for Windows (recommended)

Anthropic’s docs are explicit: Git for Windows is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead.” Grab it from git-scm.com/downloads/win — accept the default install options. Many shell-using tools (your project’s npm scripts, Husky hooks,shellcheck) work better when Git Bash is available.

Step 3 — Install Claude Code natively

Three official methods, pick one:

# Method 1 — PowerShell (recommended)
irm https://claude.ai/install.ps1 | iex

# Method 2 — CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Method 3 — WinGet
winget install Anthropic.ClaudeCode

The PowerShell installer (install.ps1) drops claude.exe into %USERPROFILE%\.local\bin\ and updates your user PATH. Close and re-open your shell (or open a fresh PowerShell window) so the PATH change takes effect.

Anthropic’s own quick-disambiguation note for Windows users: If you see ‘The token && is not a valid statement separator’, you’re in PowerShell, not CMD. If you see ‘irm is not recognized as an internal or external command’, you’re in CMD, not PowerShell. Your prompt shows PS C:\ when you’re in PowerShell and C:\ without the PS when you’re in CMD.

Verify:

claude --version
claude doctor

If you see claude is not recognized, your PATH hasn’t reloaded — open a new PowerShell window instead of re-using the one open during install. If a fresh window still fails, run echo $env:Path and confirm %USERPROFILE%\.local\bin is in there.

Step 4 — Add MCP servers (with the cmd /c wrapper)

The single most important rule for native Windows stdio MCP: wrap every npx-based server with cmd /c. Without it, you get spawn npx ENOENT. With it, you don’t. Anthropic’s own warning, surfaced in claude-code issue #4019: “Windows requires ‘cmd /c’ wrapper to execute npx.

Wrong (will fail with ENOENT):

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

Right:

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

You can also bypass npx entirely by pointing directly at node.exe with the absolute script path — useful when antivirus quarantines unsigned batch files:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
        "C:\\Users\\you\\Desktop"
      ]
    }
  }
}

Note the doubled backslashes — JSON requires \\ for a literal \. Single backslashes silently break parsing.

Step 5 — Use claude mcp add (preferred over hand-editing)

You don’t need to hand-edit %USERPROFILE%\.claude.json — the CLI knows how to write the right shape. From PowerShell:

# Stdio with cmd /c wrapper
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\you\Desktop"

# Remote HTTP (no Windows-specific quoting)
claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp

# List
claude mcp list

# Remove
claude mcp remove context7

Note the quoted Windows path — PowerShell handles single quotes and double quotes differently. If you hit quoting issues, fall back to hand-editing %USERPROFILE%\.claude.json with the JSON shape above.

Step 6 — Suppress the cmd.exe window flash (optional)

Per issue #44039, user-configured MCP servers can take a windowsHide: true field:

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

This passes windowsHide: true through to Node’s child_process.spawn(), which tells Windows to spawn the process with the CREATE_NO_WINDOW flag. The console window won’t flash on screen anymore. Built-in spawns (chroma-mcp, claude.cmd) still require an Anthropic-side fix.

The MSIX Claude Desktop config trap

If you’re using Claude Desktop (the Electron app, not Claude Code CLI) and your MCP config seems to be ignored, you may have hit issue #26073. Verbatim from the bug: The ‘Edit Config’ button confidently opens the wrong file, leading users to believe they’re editing the right config. All official documentation references %APPDATA%\Claude\ as the config location.” The actual file the app reads on MSIX installs is at:

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Open that path directly in Notepad or VS Code, merge your MCP entries into the existing JSON (don’t overwrite the preferences block), and restart Claude Desktop. The same bug doesn’t affect Claude Code CLI — its config lives at %USERPROFILE%\.claude.json outside the MSIX virtualization.

If you want to avoid this trap permanently, install Claude Desktop from the WinGet package or a non-MSIX installer channel. Anthropic ships both.

MCP server compatibility on Windows

Most popular MCP servers work on both paths if you follow the rules above (cmd /c wrapper for stdio on native, native Linux on WSL). The compatibility matrix below covers the top servers people actually install. Native Windows means the server runs without WSL and without unusual workarounds; WSL-only means it has Linux-specific dependencies that don’t resolve on native Windows; Both means it works equally well either way (these are the remote-HTTP servers, mostly).

ServerTransportNative WindowsWSL2Notes
Context7Remote HTTPYesYesHosted endpoint, no spawn issues
DeepWikiRemote HTTPYesYesHosted, no auth required
GitHub (official)Remote HTTPYesYesOAuth-based, api.githubcopilot.com/mcp
NotionRemote HTTPYesYesOAuth, mcp.notion.com/mcp
Filesystemstdio (npx)With cmd /cYesUse absolute path; doubled backslashes in JSON
Sequential Thinkingstdio (npx)With cmd /cYesCommon ENOENT example in issue #4019
Brave Searchstdio (npx)With cmd /cYesSet BRAVE_API_KEY env var
Playwrightstdio (npx)With cmd /cYesBrowser drivers install heavy; WSL2 less smooth
Puppeteerstdio (npx)With cmd /cYesSame as Playwright
Desktop Commanderstdio (npx)Yes (native paths)Limited — Windows APIOS-specific; native is the supported target
Atlassian Jira/ConfluenceRemote HTTPYesYesOAuth
FirecrawlRemote HTTP / stdioYesYesPrefer remote on Windows

The pattern is unmistakable: if a server exposes a remote HTTP endpoint, it works identically on both paths. If it only ships as stdio, native Windows requires the cmd /c wrapper, and WSL2 just works. Browse the full set on /servers; remote-transport servers are flagged on each detail page.

Cursor / VS Code / Cline on Windows

Claude Code isn’t the only MCP host. Three other popular ones with the same Windows quirks:

Cursor. Cursor reads MCP config from %USERPROFILE%\.cursor\mcp.json globally or .cursor/mcp.json per-workspace. The schema matches Claude Desktop’s — command, args, optional env — so the same cmd /c wrapper rule applies. Cursor docs at docs.cursor.com cover both stdio and streamable-HTTP transports. We have a full breakdown in Best MCP servers for Windsurf & VS Code Copilot.

VS Code Copilot Chat. Microsoft added MCP support in 2025; the workspace config lives at .vscode/mcp.json and the global config at the user-settings JSON. Same cmd /c trick on Windows. Microsoft’s own MCP servers (PowerBI, etc.) tend to use signed binaries that don’t need the wrapper.

Cline (formerly Claude Dev). Cline reads MCP config from its own settings file (varies by VS Code profile). The Cline GitHub README documents the config shape; it’s the same command/args/env pattern. The same Windows quoting and ENOENT rules apply. The Cline community has produced multiple Windows-specific guides — see issue DesktopCommanderMCP #10 for the WSL configuration thread.

Antivirus + corporate proxy gotchas

Enterprise Windows machines layer on a few extra failure modes. We can’t give exact paths because they vary by your security team’s policy, but the patterns generalize.

Antivirus quarantines unsigned scripts. CrowdStrike Falcon, SentinelOne, and Microsoft Defender ATP sometimes flag npx-fetched scripts in %APPDATA%\npm-cache or %LOCALAPPDATA%\npm-cache as suspicious because they’re unsigned, dynamically downloaded, and executed via cmd.exe. Symptoms: MCP server connects once, then disappears 30 seconds later; or connect succeeds but tool calls hang. Fix: ask your security team to add an exclusion for those paths (approximate paths only — verify with your team using Microsoft’s Defender exclusion docs).

Corporate proxy blocks npm/npx pulls. Ifnpx -y @modelcontextprotocol/server-filesystem hangs forever on first install, you’re probably behind a TLS-inspecting proxy. Configure npm:

# In an elevated PowerShell or CMD:
npm config set proxy http://corp-proxy.local:8080
npm config set https-proxy http://corp-proxy.local:8080
npm config set strict-ssl false  # Only if your proxy MITMs TLS

# Or set per-shell env vars:
$env:HTTP_PROXY  = "http://corp-proxy.local:8080"
$env:HTTPS_PROXY = "http://corp-proxy.local:8080"

For uvx-based servers (Python ecosystem), set UV_HTTP_PROXY / UV_HTTPS_PROXY. If your proxy injects a custom CA cert, you’ll also need NODE_EXTRA_CA_CERTS pointing at the cert.pem.

Group Policy locks down PowerShell. Some managed laptops set the PowerShell execution policy to AllSigned or Restricted, which blocks the install.ps1 bootstrap. Workaround: use the CMD installer (install.cmd) or the WinGet route, both of which avoid the policy gate.

Remote MCP + OAuth — the easy mode

Every Windows-specific bug listed in this guide originates in the stdio transport: process spawning, batch-file resolution, MSIX virtualization, console window flashing, AV quarantine. Remote MCP servers don’t have any of those problems. They’re an HTTPS endpoint and an optional OAuth flow.

If a server you want offers a hosted endpoint, prefer it on Windows:

# All identical on native Windows + WSL + macOS:
claude mcp add --transport http context7  https://mcp.context7.com/mcp
claude mcp add --transport http deepwiki  https://mcp.deepwiki.com/mcp
claude mcp add --transport http github    https://api.githubcopilot.com/mcp
claude mcp add --transport http notion    https://mcp.notion.com/mcp
claude mcp add --transport http stripe    https://mcp.stripe.com
claude mcp add --transport http linear    https://mcp.linear.app/mcp

For OAuth-protected endpoints, Claude Code opens a browser window the first time and stores the resulting token. On Windows that just works — the token cache lives in %USERPROFILE%\.claude\.

Compare the docs-RAG options in our Context7 vs DeepWiki vs Ref Tools vs Docfork deep-dive — three of the four are remote-HTTP servers, so they sidestep every issue in this guide. The fourth (Ref Tools) ships a stdio shim that works identically on Windows with the cmd /c wrapper.

Diagnosing failures

If /mcp is empty, a server hangs, or you get a cryptic error, run through this checklist before opening a bug. The fastest path to a fix is identifyingwhich failure you’re hitting.

Step 1 — Does claude itself work?

claude --version
claude doctor

If --version fails: PATH issue, see “claude is not recognized” in the FAQ. If doctor reports issues: read them, they’re usually accurate.

Step 2 — Does Node work?

# Native Windows (PowerShell):
where node
where npx
node --version
npx --version

# WSL:
which node
which npx
node --version

If where npx reports a path but Claude Code still says ENOENT, you’re hitting the cmd /c problem — apply the wrapper.

Step 3 — What does claude mcp list show?

claude mcp list

Three possible outcomes. Empty. Either no servers configured (check ~/.claude.jsonor %USERPROFILE%\.claude.json) or you’re hitting issue #32951 (native-Windows stdio loading bug — workaround: switch to WSL or use remote-HTTP servers). Lists servers but they’re “not connected”. The server is configured but failing to start. Check the command and args, then run the exact spawn manually to see the real error. Lists and connects. You’re done — restart Claude Code if tools still aren’t firing in chat.

Step 4 — Run the spawn manually

Reproduce what Claude Code does internally, but in your own terminal:

# Native Windows PowerShell:
cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\you\Desktop"

# WSL:
npx -y @modelcontextprotocol/server-filesystem ~/projects

Then send a JSON-RPC initialize message manually:

# In WSL or Git Bash:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | npx -y @modelcontextprotocol/server-filesystem ~/projects

A working MCP server returns a JSON-RPC response with protocolVersion and capabilities. If it doesn’t — that’s your real bug, not Claude Code’s.

Step 5 — Check the right config file

Claude Code writes server entries to ~/.claude.json (WSL) or %USERPROFILE%\.claude.json (native Windows). Project-scope servers go to .mcp.json at the project root. Claude Desktop on MSIX reads from %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json — not the path the “Edit Config” button opens. See issue #26073 above.

Step 6 — When all else fails, restart and re-check

Claude Code reads MCP config at startup; there’s no live reload. Quit, reopen, run claude mcp list again. If you’re using the desktop app, fully quit from the system tray (right-click → Quit, not just close the window).

Community signal

Three primary-source quotes, all linked to verifiable public artifacts.

Local stdio MCP servers configured in ~/.mcp.json, ~/.claude/settings.json, and project-level .mcp.json are completely ignored by Claude Code on native Windows. The /mcp command does not list them at all — they are absent, not errored. Cloud-hosted claude.ai MCP servers (Miro, Egnyte, Figma, Asana, Microsoft 365) load and work correctly. The same configuration works correctly when running Claude Code under WSL on the same machine.

StingyJack (GitHub issue #32951) · Blog

Open bug at the time of writing. Claude Code 2.1.72, Windows 11 Enterprise. The clearest summary of why WSL is still the recommended path.

Source
There are two claude_desktop_config.json files on the system: the file 'Edit Config' opens (the wrong one) and the file the app actually reads (in the MSIX virtualized filesystem). When a user adds MCP server configuration to file #1 (as instructed by the UI and documentation), the app reads file #2 and finds no MCP servers configured. The MCP servers never start.

0xc4b4l (GitHub issue #26073) · Blog

The MSIX virtualization bug. Detailed reproduction with exact path strings; the canonical reference for 'why is my Claude Desktop config ignored on Windows'.

Source
Everything lives in your Linux distro; Windows just launches it. No admin needed — wsl.exe is already on the PATH.

Mads Bruun Hovgaard (Medium) · Blog

The argument for WSL2 as the easiest path on locked-down corporate Windows machines. Demonstrates a wsl.exe --exec bash -lc invocation pattern that lets a Windows-side Claude Desktop launch a WSL-side filesystem MCP server.

Source

Frequently asked questions

Do I need WSL to run Claude Code on Windows in 2026?

No. Anthropic's official docs list Windows 10 1809+ and Windows Server 2019+ as supported, with PowerShell or CMD as valid shells; Git for Windows is recommended but not required. WSL2 is still the path of least resistance for stdio MCP servers because the Linux ecosystem they were written against is the same one a WSL2 Ubuntu shell provides.

Why does my MCP server show 'spawn npx ENOENT' on Windows?

Node's child_process.spawn doesn't go through a shell on Windows by default, and npx is a .cmd batch script, not a .exe. The fix is to wrap the command with cmd /c — change command: 'npx' to command: 'cmd', args: ['/c', 'npx', '-y', '<package>']. This is documented in claude-code issue #4019 and is the same shape that works on Claude Desktop.

Why is /mcp empty on native Windows even though my config is correct?

There are two known classes of failures. First, GitHub issue #32951 reports that local stdio MCP servers configured in ~/.mcp.json or ~/.claude/settings.json are completely missing from /mcp on native Windows while the same config works under WSL on the same machine. Second, GitHub issue #26073 documents that on MSIX-installed Claude Desktop, the 'Edit Config' button opens a path the app does not actually read from — config edits silently disappear.

What is the MSIX claude_desktop_config.json bug?

MSIX installations of Claude Desktop run inside Windows' virtualized filesystem. The 'Edit Config' button opens %APPDATA%\Claude\claude_desktop_config.json, but the app actually reads %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json. They are two separate files that never sync. Edit the LocalCache path directly. (Source: GitHub issue #26073.)

Should I install Node.js for Windows or use nvm inside WSL?

If you're on the WSL path, install Node via nvm inside WSL (curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash, then nvm install --lts). If you're on the native Windows path, use the Node.js LTS Windows installer from nodejs.org or nvm-windows. Mixing — Node on Windows but Claude Code in WSL, or vice versa — is the source of about half the path-resolution complaints in the bug tracker.

Can I use Cursor / VS Code Copilot Chat / Cline with MCP on Windows?

Yes. Cursor reads ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) and supports stdio, SSE, and streamable HTTP transports per the official Cursor docs. VS Code's GitHub Copilot Chat reads workspace .vscode/mcp.json. Cline reads its own settings file. The same cmd /c wrapper trick applies to all of them when using stdio.

Why do cmd.exe windows briefly flash on screen when I start Claude?

GitHub issue #44039 documents that on Windows, the Claude Desktop app spawns several background processes through cmd.exe wrappers without the windowsHide: true Node.js spawn option. For your own MCP servers, you can add 'windowsHide': true to each entry in claude_desktop_config.json to suppress the flash. The built-in spawns (chroma-mcp, claude.cmd) require an Anthropic-side fix.

What command installs Claude Code on Windows 10 / 11 natively?

Per code.claude.com/docs/en/setup, the official commands are: PowerShell — irm https://claude.ai/install.ps1 | iex. CMD — curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. WinGet — winget install Anthropic.ClaudeCode. The native installer auto-updates in the background; WinGet does not.

How do I install Claude Code inside WSL Ubuntu in 2026?

Inside your WSL shell, run curl -fsSL https://claude.ai/install.sh | bash. That's the same script the macOS and Linux native installers use; it puts the claude binary in ~/.local/bin and auto-updates. Make sure Node.js 18+ is installed inside WSL (nvm install --lts) before configuring stdio MCP servers that npx-pull packages.

What's the difference between local, user, and project MCP scope on Windows?

claude mcp add accepts --scope local (the default; writes the server into ~/.claude.json under your current project), --scope user (writes to your global config so the server is available across all projects), and --scope project (writes to .mcp.json in the repo so it's shared with collaborators). On Windows, ~/.claude.json resolves to %USERPROFILE%\.claude.json. The scope matters when debugging /mcp empties — you may be looking at the wrong file.

Will antivirus or corporate proxy block MCP servers on Windows?

Common in enterprise setups. Antivirus tools (CrowdStrike, SentinelOne, Defender ATP) sometimes quarantine the npm/uvx-fetched stdio binaries because they're unsigned scripts spawned from cmd.exe. Add an exclusion for your %APPDATA%\npm and %LOCALAPPDATA%\npm-cache directories (verify exact paths with your security team), and configure npm/pip/uv to use your corporate proxy via HTTP_PROXY, HTTPS_PROXY, and NPM_CONFIG_PROXY environment variables. Remote MCP servers over HTTPS (mcp.context7.com, mcp.deepwiki.com, mcp.notion.com) usually pass corporate firewalls cleanly because they're just outbound TLS.

Should I prefer stdio or remote (streamable HTTP) MCP servers on Windows?

Remote, when you have the choice. Stdio servers are where every Windows-specific bug listed in this guide originates: spawn semantics, batch file resolution, MSIX virtualization, antivirus quarantine, cmd.exe console flashing. Remote servers are just an HTTPS endpoint — claude mcp add --transport http <name> <url> — and they sidestep the entire process-spawning surface. Use stdio only when you must run a binary locally (filesystem, desktop-commander, custom internal tools).

How do I diagnose 'claude is not recognized' on Windows after install?

Open a fresh PowerShell window — the installer added ~/.local/bin to your PATH and your existing shell hasn't reloaded it. If a new window still fails, check that %USERPROFILE%\.local\bin is in your PATH (echo $env:Path), then run claude doctor from a working shell to surface diagnostics. The 'where' command (where node, where claude, where npx) is the most useful one-liner for path debugging on Windows.

Where is .claude.json on Windows?

%USERPROFILE%\.claude.json — typically C:\Users\<you>\.claude.json. The MCP server entries claude mcp add writes are stored here. Project-scope servers go to a .mcp.json at the project root. If you're editing this file by hand, restart Claude Code so it re-reads the file; there's no live reload.

Sources

Anthropic official

GitHub issues (verified, verbatim quoted above)

  • #22706 — “MCP servers not connecting on Windows 11 despite correct configuration” (DavidRHerbert, 2026-02-03, closed)
  • #26073 — “Windows MSIX: ‘Edit Config’ opens wrong claude_desktop_config.json” (0xc4b4l, 2026-02-16, open)
  • #32951 — “Local stdio MCP servers not loaded on native Windows” (StingyJack, 2026-03-10, open)
  • #4019 — “Convex MCP Configuration: Windows Execution Wrapper Required” — source of the cmd /c rule
  • #44039 — “Windows: visible cmd.exe windows flash on screen when spawning MCP servers” (Taejin321, 2026-04-06) — source of the windowsHide workaround

Microsoft + Node

Other clients

Internal links

What to do next

If you got claude mcp list working with three servers connected, you’re past the hardest part. Two productive next moves:

Add a docs-RAG server so Claude stops hallucinating outdated APIs

Context7 or DeepWiki — both remote-HTTP, both cross-platform. See our four-way comparison.

Layer Claude Code skills on top of MCP for repeatable workflows

Skills are versioned prompt-and-tool bundles you invoke by name. See our skills primer or browse the catalog at /skills.

Don’t stack five stdio servers in one config

Every stdio server adds startup latency, an OS process, and tool descriptions that eat your context window. Pick the two you actually use; the rest go behind a remote-HTTP endpoint or stay uninstalled.

Don’t hand-edit %USERPROFILE%\.claude.json while Claude Code is running

The CLI rewrites the file on shutdown; your edits get overwritten. Use claude mcp add for new entries; only edit the file directly when Claude is fully closed.

Keep reading