Windows 配置 Claude Code Playwright MCP：三个连接失败陷阱

在 Windows 上配置 Claude Code 的 Playwright MCP，看似只需执行一条添加命令，实际却可能反复遇到 Failed to connect。麻烦之处在于，缓存、进程启动和 Shell 参数转换造成的故障几乎没有表面差异。下面从这三个层面拆解原因，并逐步验证最终配置是否真正可用。

Claude Code 配置 Playwright MCP 踩坑记：Windows 下我踩了三个坑

结论先行

如果你在 Windows 上照着文档执行：

claude mcp add playwright -- npx @playwright/mcp@latest

然后拿到 ✗ Failed to connect，那你大概率撞上了下面三个坑里的一个或多个。它们彼此独立，症状却长得一模一样。

能跑通的最终配置是这样：

{
  "playwright": {
    "type": "stdio",
    "command": "cmd",
    "args": ["/c", "npx", "-y", "@playwright/mcp@latest"],
    "env": {}
  }
}

下面记录完整的排查过程。

环境

• Windows 11（10.0.26100）
• Git Bash / MSYS
• Node v24.19.0，npm 11.17.0
• Claude Code CLI
• @playwright/mcp 0.0.80

坑一：npx 缓存里的包是残缺的

现象：服务器启动即崩，日志里是

Error: Cannot find module 'playwright-core/lib/utilsBundle'
Require stack:
- [email protected]

排查：先去 npx 缓存目录看依赖到底在不在。

ls ~/AppData/Local/npm-cache/_npx/*/node_modules/

结果 @playwright、playwright、playwright-core 三个目录都在——看起来没问题。

但继续往里看：

ls .../node_modules/playwright-core/

空的。 目录存在，里面什么都没有。

根因：npx 的安装过程被中断了（我在装包时用 timeout 60 把进程掐了）。npm 创建了目录但没写完内容，留下一个空壳。之后再跑 npx，它看到目录已存在，以为装好了，直接使用——于是每次都崩在这个模块缺失上。

解决：删掉损坏的缓存条目，重新完整安装。

rm -rf ~/AppData/Local/npm-cache/_npx/9833c18b2d85bc59
npx -y @playwright/mcp@latest --help   # 别打断，等它装完

教训：不要在 npx 装包过程中 Ctrl+C 或加 timeout。如果已经这么干过、并出现莫名其妙的模块缺失，先清缓存再说。

坑二：Windows 下 Claude Code 没法直接启动 npx

清完缓存，手动测 stdio 握手，是通的：

printf '%sn' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx -y @playwright/mcp@latest

正常返回：

{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"Playwright","version":"1.63.0-alpha-2026-08-31"}},"jsonrpc":"2.0","id":1}

但 claude mcp list 依旧是 ✗ Failed to connect。

根因：Claude Code 启动 MCP 服务器时不走 shell，而是直接 spawn("npx", args)。而在 Windows 上，npx 实际是 npx.cmd——一个批处理文件。Node 的 child_process.spawn 在不带 shell: true 的情况下无法执行 .cmd，所以进程根本没起来。

解决：显式用 cmd 包一层。

claude mcp add playwright -s user -- cmd /c npx -y @playwright/mcp@latest

坑三：Git Bash 把 /c 变成了 C:/

执行上面那条命令后，Claude Code 回显的却是：

Added stdio MCP server playwright with command: cmd C:/ npx -y @playwright/mcp@latest

/c 变成了 C:/，参数废了。

根因：MSYS（Git Bash）会对看起来像 Unix 路径的参数做自动转换。/c 被当成"根目录下的 c"，翻译成了 Windows 路径 C:/。

解决：关掉路径转换。

MSYS_NO_PATHCONV=1 claude mcp add playwright -s user -- cmd /c npx -y @playwright/mcp@latest

这次回显正确了：

Added stdio MCP server playwright with command: cmd /c npx -y @playwright/mcp@latest

验证

claude mcp list

playwright: cmd /c npx -y @playwright/mcp@latest - ✓ Connected

最终配置落在 C:Users<你的用户名>.claude.json：

{
  "playwright": {
    "type": "stdio",
    "command": "cmd",
    "args": ["/c", "npx", "-y", "@playwright/mcp@latest"],
    "env": {}
  }
}

再跑一次真实调用——导航到页面并截图，浏览器渲染正常，整个链路就通了。

如果你的机器上还没装 Playwright 的浏览器二进制，补一句 npx playwright install chromium。

补充：配置好了，当前会话也看不到工具

MCP 工具是在会话启动那一刻加载的。你新加了一个服务器，正在运行的那个会话不会自动获得它的工具。在 Claude Code 里输入 /mcp，对它 reconnect 一下即可——不需要重启整个进程。

小结

三个坑，分属三个不同层面：

坑	层面	一句话
一	npm 缓存	npx 安装被打断会留下空壳目录，清缓存重装
二	进程启动	Windows 上 .cmd 必须走 shell，用 cmd /c 包一层
三	Shell 差异	MSYS 会悄悄改写 /c，用 MSYS_NO_PATHCONV=1 关掉

它们的共同点是：症状全都是 Failed to connect，而根因分别落在缓存、进程模型、shell 三个完全不相干的地方。

所以遇到这个报错，别只盯着配置本身看，从下往上逐层验：

1. 包完整吗？（去 npx 缓存里看依赖目录是否为空）
2. 手动能握手吗？（直接喂一个 initialize 请求给服务器）
3. Claude Code 起得来进程吗？（Windows 上 .cmd 需要 shell）
4. 参数有没有被 shell 改过？（MSYS 路径转换）

逐层排除，比对着配置文件反复改要快得多。