网上的 Claude Code + MCP 教程很多,但我在 Windows 上照着做,好几次都卡在"命令明明一样,就是连不上",这是最让人绝望的,每个字母都认真核对后都还是不行。下面三个坑是我这两天在自己电脑上一个个复现出来的,每个都给出能直接用的解决办法。 先说结论:Windows PowerShell 像一坨屎
测试环境:Windows 11,Claude Code 2.1.318,Node.js 26 / 20.20.2,系统自带的 Windows PowerShell 5.1,Git Bash。测试用的 MCP 是官方的 @modelcontextprotocol/server-filesystem。
先说一个通用的排查办法:配完之后跑一下
claude mcp list
每个服务后面会显示 ✔ Connected 或 ✘ Failed to connect。重点看它显示的那条命令和你输入的是不是一样——下面第 2 个坑就是靠这个发现的。
坑 1:PowerShell 里 -- 被"吃掉",报 unknown option '-y'
教程里的标准写法:
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem D:/code
在 Windows 自带的 PowerShell(5.1)里直接执行,会报:
error: unknown option '-y'
原因:PowerShell 会把单独的 -- 当成它自己的符号处理掉,传给 claude 的参数里就没有 -- 了,于是 -y 被当成了 claude 自己的选项。
解决:给 -- 加上引号:
claude mcp add fs "--" npx -y @modelcontextprotocol/server-filesystem D:/code
我实测加引号后正常添加,claude mcp list 显示 Connected。(PowerShell 7 我这台电脑没装,没测。)
坑 2:Git Bash 里 cmd /c 被改成 cmd C:/,报 Connection closed
很多老教程说 Windows 上必须写成 cmd /c npx ...。如果你是在 Git Bash 里执行:
claude mcp add fs -- cmd /c npx -y @modelcontextprotocol/server-filesystem D:/code
claude mcp list 会显示:
fs: cmd C:/ npx -y @modelcontextprotocol/server-filesystem D:/code - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed
注意看:/c 变成了 C:/。这是因为 Git Bash 会自动把看起来像路径的参数转换成 Windows 路径,/c 正好被当成了 C 盘。
解决(任选一个):
- 现在的 Claude Code 已经不需要
cmd /c了,直接写npx就行。我在 2.1.318 上实测,不加cmd /c可以直接连上:
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem D:/code
- 一定要用
cmd /c的话,在命令前加MSYS_NO_PATHCONV=1关掉路径转换:
MSYS_NO_PATHCONV=1 claude mcp add fs -- cmd /c npx -y @modelcontextprotocol/server-filesystem D:/code
坑 3:项目要用旧版 Node,MCP 要用新版 Node
项目只能跑在 Node 14/16,但 MCP 服务需要 Node 18/20 以上。用 nvm 把全局切到 20,MCP 能用了,项目又挂了。
解决:不切全局,只让这个 MCP 单独用新版 Node。
第一步,用 nvm 装上新版本,但不要 nvm use:
nvm install 20
第二步,在项目根目录的 .mcp.json 里给这个服务加一个 env,把 Node 20 的目录放到 PATH 最前面:
{
"mcpServers": {
"fs": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/code"],
"env": {
"PATH": "C:\\Users\\你的用户名\\AppData\\Roaming\\nvm\\v20.x.x;${PATH}"
}
}
}
}
nvm 的目录用 nvm root 查,后面拼上实际版本号(比如 v20.20.2)。${PATH} 会被 Claude Code 展开成原来的系统 PATH,其他命令照常能找到。
一个容易踩的错误做法:只把 command 改成 Node 20 目录里的 npx.cmd。我实测过,这样 npx 本身是用 20 跑的,但它启动的 MCP 程序还是按 PATH 找到了全局那个 Node,等于没改。一定要改 PATH。
我是这样确认的:写了一个最小的 MCP 服务,启动时把 process.version 写到日志里。加了 env.PATH 的跑在 v20.20.2,不加的跑在全局版本,claude mcp list 里两个都显示 Connected。
最后
这三个坑的共同点是:命令本身没错,是 Windows 的终端在中间改了你的参数。所以连不上的时候,先看 claude mcp list 里显示的命令和你输入的是否一致。
你在 Windows 上配 MCP 还卡过哪些地方?用的是官方 Claude 还是国产模型(DeepSeek / Kimi / GLM)?欢迎在评论区说说,我挑常见的继续实测。