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

结论先行

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

bash 复制代码

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

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

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

json 复制代码

{
  "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 缓存里的包是残缺的

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

arduino 复制代码

Error: Cannot find module 'playwright-core/lib/utilsBundle'
Require stack:
- ...\_npx\9833c18b2d85bc59\node_modules\@playwright\mcp\cli.js

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

bash 复制代码

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

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

但继续往里看：

bash 复制代码

ls .../node_modules/playwright-core/

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

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

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

bash 复制代码

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

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

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

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

bash 复制代码

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

正常返回：

json 复制代码

{"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 包一层。

bash 复制代码

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

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

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

typescript 复制代码

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

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

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

解决：关掉路径转换。

bash 复制代码

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

这次回显正确了：

bash 复制代码

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

验证

bash 复制代码

claude mcp list

bash 复制代码

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

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

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 三个完全不相干的地方。

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

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

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