最近为了给 Claude Code 加上“能自己操作浏览器”的能力我在 Windows 上折腾了 Playwright 的 MCP 服务。说好听点是配置说直白点就是踩坑光“MCP server 连不上”这一个问题就让我翻日志翻到怀疑人生。前前后后花了两三个小时才把整条链路跑通最后发现拦路的全是 Windows 环境里不起眼的细节。这篇就把我踩的三个坑写清楚npx 怎么配、浏览器内核怎么装、stdio 和 HTTP 两种模式怎么选以及最终跑通的最小配置长什么样。如果你也打算在 Windows 下让 Claude Code 接入 Playwright MCP按这篇文章的顺序走大概率能少折腾两个小时。1. 先理顺思路这套配置到底在做什么Claude Code 是跑在终端里的 AI 编程助手写代码、改文件、跑命令都很强。但默认情况下它看不到浏览器里发生了什么点不了按钮提交不了表单。如果哪天你想让 AI 去访问一个页面、抓点数据、跑几轮端到端测试光靠语言模型本身是不够的它需要一个能驱动真实浏览器的“手”。Playwright MCP 就是这只手。MCP 的全称是 Model Context Protocol一套让 AI 助手连接外部工具的标准协议。你可以把 MCP 想象成 USB-C 接口Claude Code 是电脑Playwright 是显示器MCP 就是那根标准化的数据线。只要大家都遵守同样的协议插上就能用。Playwright MCP 服务器启动后Claude Code 可以调用 browser_navigate、browser_snapshot、browser_click 这类工具从而完成页面跳转、截图、点击、读取 DOM 等浏览器操作。这套东西在 macOS 和 Linux 上配置相对顺滑一条npx playwright/mcplatest往往就完事了。但在 Windows 上同样的命令会因为环境差异、可执行文件命名规则、代码页等问题翻车。我这次的经历就是一个典型样本不是协议多难不是 Playwright 本身多难而是三个非常具体的 Windows 细节拦在路中间。1.1 Claude Code、Playwright、MCP 三者怎么配合先画清楚调用链你在 Claude Code 会话里给 AI 提需求AI 决定需要操作浏览器于是通过 MCP 协议向 Playwright MCP server 发起工具调用请求。MCP server 接收到请求后用 Playwright 库去驱动真实的 Chromium 内核执行页面跳转、点击、截图等动作再把结果返回给 Claude Code。所以整条链路由四块组成Claude Code客户端、MCP 协议通信标准、playwright/mcpMCP server 实现、Playwright 浏览器内核真正干活的浏览器实例。任何一个环节断了AI 那边的表现都是“工具调用失败”或“无法连接 MCP”。我在 Windows 上踩的三个坑刚好对应这三个非 Claude Code 的环节第一个坑是 MCP server 根本没启动起来第二个坑是 MCP server 起来了但浏览器内核找不到第三个坑是 MCP server 和浏览器内核都正常但 Claude Code 这边的传输方式对不上。搞清楚这个分层逻辑后面排查问题会快很多。1.2 Windows 下容易出问题的三层原因Windows 环境的问题集中在三层环境层、依赖层、配置层。环境层指的是 Node.js、npx、PATH 这些基础环境。Windows 下 Node 相关的命令不是以 .exe 文件存在的而是 .cmd 脚本这会导致一些不经过 shell 直接 spawn 进程的程序找不到命令。这是坑一的来源。依赖层指的是 Playwright 浏览器内核。playwright/mcp 这个包本身不捆绑浏览器需要额外执行npx playwright install chromium下载。Windows 下下载容易超时而且如果机器上同时装了 Python 版 Playwright 之类的东西浏览器缓存的版本还可能互相干扰。这是坑二的来源。配置层指的是 Claude Code 里 MCP server 的注册方式。Claude Code 支持 stdio 和 HTTP 两种传输模式playwright/mcp 也支持这两种模式但很多人不知道默认是 stdio还硬要加--port参数结果两边模式不匹配。Windows 中文系统还自带一个 GBK 编码坑会让 stdio 管道里的中文消息变成乱码。这是坑三的来源。把这三层分开看待就很容易理解为什么同样的配置在别人电脑上跑得好好的在你 Windows 上就各种报错。接下来按我踩坑的顺序逐个拆解。2. 坑一npx 找不到MCP server 启动不了这是第一个拦路虎症状非常典型我按照网上最常见的命令执行claude mcp add playwright -- npx playwright/mcplatest终端提示添加成功当时还挺高兴。结果打开 Claude Code 会话输入/mcp查看状态playwright 这一行赫然显示着 disconnected 或者 failed。再打开调试日志里面能看到类似这样的报错spawn npx ENOENT Fatal error: ENOENT: no such file or directory, spawn npx ENOENT看到 ENOENT 的第一反应是检查 Node 装了没有。但我在 cmd 里敲npx --version明明能正常输出版本号。这就让人很困惑命令行能跑凭什么 Claude Code 就跑不了2.1 症状与第一反应这里容易犯的错误就是反复重装 Node、反复改 PATH甚至怀疑是 Claude Code 版本问题。我也一度以为是不是自己装了多个 Node 版本导致 PATH 里指向了不存在的路径。检查了半天where npx也能定位到C:\Program Files\nodejs\npx.cmd路径完全没问题。真正的问题不在 PATH而在可执行文件的类型。Windows 下的 npm 和 npx 实际是npm.cmd和npx.cmd不是npx.exe。Claude Code 的 MCP 客户端在启动子进程时底层用的是 Node.js 的child_process.spawn。spawn 在 Windows 上不会像 cmd 那样自动去解析.cmd和.bat文件的执行逻辑它只会去找真正可执行的.exe文件或者调用cmd.exe /c来包装一层。如果你给 spawn 传了npx它期望找到的是npx.exe但系统里只有npx.cmd于是直接 ENOENT。这个坑在英文社区的解决方案里几乎不会提到因为 macOS 和 Linux 上npx就是一个真正的二进制文件没有这种区别。Windows 用户照抄文档第一脚就踩进去。2.2 为什么会这样Windows 的可执行文件与 spawn稍微展开一点讲原理。Windows 操作系统中可执行文件的后缀名有严格的约定.exe才是真正能被 CreateProcess 直接拉起程序.cmd和.bat本质上是脚本需要由 cmd.exe 解释执行。当你自己在终端里输入npx时终端cmd 或 PowerShell会先找到npx.cmd然后用 cmd 的规则去执行它所以一切正常。但 Claude Code 在启动 MCP server 的时候不会走终端那套交互 shell 的逻辑而是直接调用系统 API 去创建进程。它拿到npx这个名字去 PATH 里找结果只找到了npx.cmd不符合直接执行的条件就返回 ENOENT 了。想验证这个结论很简单在 cmd 里直接运行where npx你大概率会看到一条路径指向的正是.cmd结尾的文件。这说明系统认得它但 spawn 不认。2.3 解决方案npx.cmd 与 PATH 双保险解决办法有两个我建议两个都做。第一个办法也是最直接的添加 MCP server 的时候把npx改成npx.cmd。claude mcp add playwright -- npx.cmd playwright/mcplatest这个写法等于明确告诉 spawn去执行这个.cmd文件。实际测试下来npx.cmd是可以被直接 spawn 的Claude Code 收集了命令就会正常运行。第二个办法是手动编辑配置文件把命令指定成绝对路径更稳妥。Claude Code 的 MCP 配置可以写在项目级文件比如.mcp.json或者用户级配置里。手动编辑时Windows 路径里的反斜杠记得转义{ mcpServers: { playwright: { command: C:\\Program Files\\nodejs\\npx.cmd, args: [playwright/mcplatest] } } }如果你安装 Node 时改了路径先执行where npx拿到实际路径再填进去。如果不想写绝对路径至少确保系统 PATH 里包含 Node.js 的安装目录并且使用npx.cmd这个写法。另外提一个很容易被忽略的点改完 PATH 之后已经打开的终端窗口不会自动生效必须新开一个终端再启动 Claude Code。我有一次改完 PATH 忘了重启终端又在原地折腾了十分钟属于纯笨。3. 坑二浏览器内核装不上AI 有工具也用不了第一个坑解决之后MCP server 总算从 failed 变成了 connected。我当时以为大功告成马上给 Claude 下指令“打开 example.com看看页面上有什么”。结果它调用了 browser_navigate 工具很快就返回了一段刺眼的报错browserType.launch: Executable doesnt exist at C:\Users\...\ms-playwright\chromium-XXXX\chrome-win\chrome.exe Please run npx playwright install chromium看到这个我第一反应是我不是已经装了 Playwright 吗怎么还要装后来才意识到这里说的“安装 Playwright”和“安装浏览器内核”是两码事。3.1 现象所有浏览器操作都报错从现象上看只要 AI 尝试做任何和浏览器有关的动作结果都是同一个错误找不到可执行文件。这不是因为 Playwright 库没装而是因为 Playwright 库和浏览器内核是分离的。库负责写自动化逻辑内核才是真正渲染页面、执行 JavaScript 的那个浏览器进程。npm 包 playwright/mcp 默认在启动时会尝试找你本机上对应版本的 Chromium。如果没有它就罢工。这是设计上的选择不是 bug——浏览器内核体积不小如果每个依赖 Playwright 的包都自动下载一份磁盘很快就炸了。我当时电脑上其实装过 Python 版 Playwright也跑过playwright install但 Node 生态的 Playwright 浏览器缓存索引和 Python 版的不完全互通尤其是版本号对不上的时候Node 这边依然会认为“找不到合适的浏览器”。3.2 深层原因MCP 包不内置浏览器更准确地说每个通过 npm 安装的 Playwright 相关包都对应一个具体的浏览器版本。playwright/mcp 在安装时会继承当前环境里 Playwright 库的版本并期望浏览器缓存目录里存在那个版本的内核。你用 Python 的 Playwright 装的内核版本可能不同缓存在同一个%USERPROFILE%\AppData\Local\ms-playwright目录下但目录名是按版本号区分的。Node 这边要找 chromium-XXXXPython 那边可能装的是 chromium-YYYY两者互不认账。所以解决方式不是“我装过 Playwright 了啊”而是“在 Node 环境里把当前版本对应的内核安装一遍”。在 Windows 下我建议先确保当前工作目录的 PATH 和网络环境都正常然后执行npx playwright install chromium命令执行完会去微软和 Google 等 CDN 下载几十到上百 MB 的内核文件。如果网络状况一般很容易下载到一半卡死特别是首次安装时。遇到这种问题可以配置国内的 npm 镜像同步源作为 Playwright 的下载地址。3.3 两种解法手动安装内核 / 直接调用系统 Chrome解法一就是手动安装内核上面已经写了。怕下载慢的话把环境变量指到 npmmirrorCMD 下执行set PLAYWRIGHT_DOWNLOAD_HOSThttps://cdn.npmmirror.com/binaries/playwright npx playwright install chromiumPowerShell 下执行$env:PLAYWRIGHT_DOWNLOAD_HOST https://cdn.npmmirror.com/binaries/playwright npx playwright install chromium下载完成后建议重启一下 Claude Code让 MCP server 重新启动再去测试浏览器操作。解法二更省事如果你的 Windows 系统装了 Chrome、Edge 或 Chromium 系浏览器可以让 playwright/mcp 直接使用系统浏览器省掉下载内核那一步。Edge 在 Windows 上基本是预装的用起来很稳。claude mcp add playwright -- npx.cmd playwright/mcplatest --browser chrome--browser chrome会让 Playwright 去寻找本机的 Chrome不再要求 ms-playwright 缓存目录里有对应版本的 Chromium。如果你系统里只有 Edge可以把参数写成--browser msedge。我用 Edge 试过速度和稳定性都很不错毕竟 Edge 和 Chromium 同源。注意--browser chrome参数必须加在 MCP server 的 args 里。如果你用的是之前的配置文件记得把 args 改成类似[playwright/mcplatest, --browser, chrome]。两个解法选一个就行。我自己的建议是如果电脑上有 Edge 或 Chrome直接走解法二最快如果没有就走解法一反正装一次后面都能复用。4. 坑三传输模式与端口问题配置对了还是连不上前两个坑解决之后MCP server 显示已连接浏览器内核也有了但诡异的事情出现了AI 调用某些工具的时候正常另一些工具却一直转圈到最后直接超时。更迷惑的是有一次我在 MCP server 的启动参数里加了--port 8931结果 Claude Code 彻底连不上了。这时候我才意识到传输模式这个坑比前面两个更隐蔽。4.1 三种“连接不上”的真实场景先说三种我当时遇到的真实场景。场景一Claude Code 显示 connected但 AI 一调用工具就超时日志里没有明显报错。这种情况通常是因为 MCP server 进程起来了但两边对消息的处理方式不一致或者消息卡在管道里没被正确解析。场景二我在手动测试npx playwright/mcplatest的时候为了让其他程序也能访问加了--port 8931然后还把这个参数写进了 Claude Code 的配置。结果 Claude Code 以 stdio 模式去连接一个启动在 HTTP 模式下的 server两边完全对不上自然连不上。场景三换成 HTTP/SSE 模式之后端口被其他程序占用了MCP server 启动失败Claude Code 持续显示红色摇头状态。这三类问题的根源都指向一件事Claude Code 和 playwright/mcp 之间到底用什么模式通信必须明确。4.2 stdio 与 HTTP别把两种模式混着配playwright/mcp 默认是 stdio 模式MCP server 作为一个子进程被 Claude Code 拉起双方通过标准输入输出流一条一条交换 JSON-RPC 消息。这个模式不需要端口不占网络资源也不存在局域网暴露的问题是本机使用最合理的选择。如果你手动执行 playwright/mcp 命令行工具什么都不加它就是用 stdio 模式。Claude Code 的claude mcp add默认添加的也是 stdio server。只有当你指定--port参数时playwright/mcp 才会切换成 HTTP 模式监听一个本地端口等着客户端通过 HTTP 请求来连。此时 Claude Code 那边应该用--transport http加 URL 的方式注册而不是默认的 stdio 方式。手动编辑配置时stdio 模式对应的配置是{ mcpServers: { playwright: { command: npx.cmd, args: [playwright/mcplatest] } } }如果你偏要用 HTTP 模式那配置应该长这样不同版本字段名会有细微差异{ mcpServers: { playwright: { type: http, url: http://127.0.0.1:8931/mcp } } }这里最容易犯的错就是混着配command 和 args 都写了还加了一个type: http或者后来把 URL 也写上。结果 Claude Code 内部就晕了到底该走子进程还是该访问 URL状态一直表现为 failed 或超时。我在这一步反复删了加、加了删最后才反应过来文档里写的是“二选一”不是“都写上”。提示在本机日常使用强烈建议用 stdio 模式也就是不要加--port保持默认。HTTP 模式适合 MCP server 独立部署、或者局域网远程连接这种真正的服务化场景。另外如果你因为某种原因开了 HTTP 模式务必确认端口只绑定 127.0.0.1不要绑 0.0.0.0。MCP server 可以控制浏览器等于一个没有鉴权的远程控制接口暴露出去非常危险。4.3 端口占用排查与 UTF-8 编码保护如果你确实要用 HTTP 模式端口 8931 是我随便举例用的实际选个没被占用的端口就行。Windows 下查端口占用很简单netstat -ano | findstr 8931如果结果里有 LISTENING 状态且不是你预期的进程用tasklist | findstr PID号看是哪个程序占着然后去任务管理器结束它或者换个端口重新启动。还有一种 Windows 特有的坑需要单独说编码。这个坑在中文系统上特别容易出现尤其是当你的 Windows 系统语言是中文默认代码页是 936GBK而 MCP 协议本身要求 UTF-8 编码的 JSON-RPC 消息。如果 Claude Code 和 playwright/mcp 之间传的中文消息以 GBK 字节流出接收方按 UTF-8 解析轻则日志乱码重则直接导致协议层消息解析失败。症状就是MCP server 明明起来了但 Claude Code 那边始终收不到有效响应工具调用一直卡住。有效的处理办法有两种。一是在启动 Claude Code 之前的终端里执行chcp 65001把代码页切到 UTF-8再启动claude。二是在 Windows 设置里勾选“使用 Unicode UTF-8 提供全球语言支持”一劳永逸不过需要重启。对于大部分只想快速跑通的人来说推荐直接用chcp 65001副作用最小。5. 一次跑通的完整配置流程Windows 11 实测三个坑都说完了但光知道坑不够还得给一套能直接照抄的流程。下面这套配置是我在 Windows 11 上实际跑通的目标是让 Claude Code 能通过 Playwright MCP 打开浏览器、访问页面、截图、读取页面内容。整个过程大约十分钟。5.1 环境准备清单开始之前确认三件事Node.js 版本不低于 18推荐 20 LTS。命令行检查node -v。Claude Code 已安装并能正常启动。命令行检查claude --version。磁盘剩余空间不少于 2GB浏览器内核要占几百 MB。如果你电脑上有 Chrome 或 Edge流程会少一步。没有的话也不碍事后面装内核就行。5.2 添加 MCP 并验证连接第一种情况用系统 Chrome。claude mcp add playwright -- npx.cmd playwright/mcplatest --browser chrome第二种情况没有 Chrome想用 Playwright 自带的 Chromium 内核先装内核再添加 MCP。npx playwright install chromium claude mcp add playwright -- npx.cmd playwright/mcplatest添加完执行claude mcp list看到 playwright 那一行的状态不是 failed说明注册这一步过了。如果显示 disconnected回看第 2 章的内容检查是不是又写成npx没写npx.cmd。然后启动 Claude Code 会话输入/mcp正常情况下playwright 会出现在已连接列表里。如果这里显示没有连接先用claude mcp remove playwright删掉再重新添加别直接在配置里手动改很容易改乱。5.3 用一个真实任务测试端到端链路命令行验证通过后在 Claude Code 里提一个简单任务“使用 playwright 打开 https://example.com截取页面截图保存到当前目录并告诉我页面标题。”我实测的时候Claude 会先调用 browser_navigate 打开页面再调用 browser_snapshot 获取页面结构最后调用 browser_screenshot 保存图片。如果你的配置正确这个过程通常不会超过 30 秒。如果它说“没有找到截图工具”怀疑是传输模式配置错了回到第 4 章检查。任务完成后当前目录下会多一个 PNG 图片文件打开确认内容是不是 example.com 的页面。页面上那一行经典的 “Example Domain” 能被 AI 读取出来就说明整条链路已经通了。注意我推荐用 example.com 这种完全中立的测试站点避免访问不稳定的外部服务导致误判。先把链路跑通再让它去操作你真正要测的网站。5.4 常见失败时的回滚技巧如果中途改坏了配置最稳妥的做法不是手动编辑 JSON而是用 Claude Code 自己的命令删掉重加claude mcp remove playwright claude mcp add playwright -- npx.cmd playwright/mcplatest删除之前可以在claude mcp list里看一眼当前的配置详情。如果连 list 都出不来多半是 JSON 语法坏了去项目目录或用户目录找.mcp.json和~/.claude.json备份一份之后把关于 playwright 的段落删掉再重新添加。6. 常见问题速查与经验总结这段时间过来我把 Windows 上配置 Playwright MCP 的问题整理成一个速查表。以后再遇到类似情况直接按表排查速度会快很多。6.1 问题速查表症状可能原因解决方法spawn npx ENOENTMCP 一直 disconnectedWindows 下 npx 是 .cmdspawn 找不到把 npx 改成 npx.cmd或用 where npx 取绝对路径浏览器操作报 Executable doesnt existplaywright/mcp 默认不含浏览器内核执行 npx playwright install chromium或用 --browser chrome/msedge 调用系统浏览器下载 chromium 卡住或失败网络访问 CDN 不稳定设置 PLAYWRIGHT_DOWNLOAD_HOST 为国内镜像源重新执行 installMCP server 已连接但工具调用一直超时stdio 模式与 HTTP 模式混配或编码问题去掉 --port 参数保持 stdio在终端执行 chcp 65001 切到 UTF-8端口启动失败提示地址被占用HTTP 模式下端口被其他程序占用用 netstat -ano 查找占用进程结束进程或换端口中文日志乱码协议消息异常中文 Windows 默认 GBK 代码页chcp 65001或在系统设置里开启 UTF-8 Beta 选项修改配置后仍然失败手动改 JSON 导致语法或结构错误用 claude mcp remove 删除后重新添加不要手硬改6.2 个人使用体会与建议Windows 下做浏览器自动化这件事这几年其实已经很成熟了Playwright 官方对 Windows 的支持本来就不差。真正让人头疼的往往不是框架本身而是环境细节。比如 .cmd 文件、代码页、PATH 不生效、端口占用它们单个看起来都不难叠在一起就特别容易让人崩溃。我自己跑通之后最大的体会是不要拿着一份 macOS 的教程在 Windows 上无脑复制。遇到报错先看 Clade Code 的 debug 日志MCP server 这层出了问题日志里多半有明确线索。其次能用命令行完成的操作不要手动编辑 JSON降低出错概率。最后先把简单场景跑通再叠加复杂度不要一上来就让 AI 操作一个登录后才能访问的站点那样即使失败了你也分不清是 MCP 的问题还是目标网站的问题。如果后续你想玩更深一点我建议试试这几个方向用 screenshot 做视觉回归对比用 browser_snapshot 让 AI 理解动态页面的结构或者把 playwright/mcp 跑在固定端口上让多个 Claude Code 会话共享同一个浏览器控制服务。每个方向都有各自的坑但基于现在这条已经跑通的链路探索起来会轻松很多。
Windows下Playwright MCP配置指南：避开npx、浏览器内核与传输模式三大坑
最近为了给 Claude Code 加上“能自己操作浏览器”的能力我在 Windows 上折腾了 Playwright 的 MCP 服务。说好听点是配置说直白点就是踩坑光“MCP server 连不上”这一个问题就让我翻日志翻到怀疑人生。前前后后花了两三个小时才把整条链路跑通最后发现拦路的全是 Windows 环境里不起眼的细节。这篇就把我踩的三个坑写清楚npx 怎么配、浏览器内核怎么装、stdio 和 HTTP 两种模式怎么选以及最终跑通的最小配置长什么样。如果你也打算在 Windows 下让 Claude Code 接入 Playwright MCP按这篇文章的顺序走大概率能少折腾两个小时。1. 先理顺思路这套配置到底在做什么Claude Code 是跑在终端里的 AI 编程助手写代码、改文件、跑命令都很强。但默认情况下它看不到浏览器里发生了什么点不了按钮提交不了表单。如果哪天你想让 AI 去访问一个页面、抓点数据、跑几轮端到端测试光靠语言模型本身是不够的它需要一个能驱动真实浏览器的“手”。Playwright MCP 就是这只手。MCP 的全称是 Model Context Protocol一套让 AI 助手连接外部工具的标准协议。你可以把 MCP 想象成 USB-C 接口Claude Code 是电脑Playwright 是显示器MCP 就是那根标准化的数据线。只要大家都遵守同样的协议插上就能用。Playwright MCP 服务器启动后Claude Code 可以调用 browser_navigate、browser_snapshot、browser_click 这类工具从而完成页面跳转、截图、点击、读取 DOM 等浏览器操作。这套东西在 macOS 和 Linux 上配置相对顺滑一条npx playwright/mcplatest往往就完事了。但在 Windows 上同样的命令会因为环境差异、可执行文件命名规则、代码页等问题翻车。我这次的经历就是一个典型样本不是协议多难不是 Playwright 本身多难而是三个非常具体的 Windows 细节拦在路中间。1.1 Claude Code、Playwright、MCP 三者怎么配合先画清楚调用链你在 Claude Code 会话里给 AI 提需求AI 决定需要操作浏览器于是通过 MCP 协议向 Playwright MCP server 发起工具调用请求。MCP server 接收到请求后用 Playwright 库去驱动真实的 Chromium 内核执行页面跳转、点击、截图等动作再把结果返回给 Claude Code。所以整条链路由四块组成Claude Code客户端、MCP 协议通信标准、playwright/mcpMCP server 实现、Playwright 浏览器内核真正干活的浏览器实例。任何一个环节断了AI 那边的表现都是“工具调用失败”或“无法连接 MCP”。我在 Windows 上踩的三个坑刚好对应这三个非 Claude Code 的环节第一个坑是 MCP server 根本没启动起来第二个坑是 MCP server 起来了但浏览器内核找不到第三个坑是 MCP server 和浏览器内核都正常但 Claude Code 这边的传输方式对不上。搞清楚这个分层逻辑后面排查问题会快很多。1.2 Windows 下容易出问题的三层原因Windows 环境的问题集中在三层环境层、依赖层、配置层。环境层指的是 Node.js、npx、PATH 这些基础环境。Windows 下 Node 相关的命令不是以 .exe 文件存在的而是 .cmd 脚本这会导致一些不经过 shell 直接 spawn 进程的程序找不到命令。这是坑一的来源。依赖层指的是 Playwright 浏览器内核。playwright/mcp 这个包本身不捆绑浏览器需要额外执行npx playwright install chromium下载。Windows 下下载容易超时而且如果机器上同时装了 Python 版 Playwright 之类的东西浏览器缓存的版本还可能互相干扰。这是坑二的来源。配置层指的是 Claude Code 里 MCP server 的注册方式。Claude Code 支持 stdio 和 HTTP 两种传输模式playwright/mcp 也支持这两种模式但很多人不知道默认是 stdio还硬要加--port参数结果两边模式不匹配。Windows 中文系统还自带一个 GBK 编码坑会让 stdio 管道里的中文消息变成乱码。这是坑三的来源。把这三层分开看待就很容易理解为什么同样的配置在别人电脑上跑得好好的在你 Windows 上就各种报错。接下来按我踩坑的顺序逐个拆解。2. 坑一npx 找不到MCP server 启动不了这是第一个拦路虎症状非常典型我按照网上最常见的命令执行claude mcp add playwright -- npx playwright/mcplatest终端提示添加成功当时还挺高兴。结果打开 Claude Code 会话输入/mcp查看状态playwright 这一行赫然显示着 disconnected 或者 failed。再打开调试日志里面能看到类似这样的报错spawn npx ENOENT Fatal error: ENOENT: no such file or directory, spawn npx ENOENT看到 ENOENT 的第一反应是检查 Node 装了没有。但我在 cmd 里敲npx --version明明能正常输出版本号。这就让人很困惑命令行能跑凭什么 Claude Code 就跑不了2.1 症状与第一反应这里容易犯的错误就是反复重装 Node、反复改 PATH甚至怀疑是 Claude Code 版本问题。我也一度以为是不是自己装了多个 Node 版本导致 PATH 里指向了不存在的路径。检查了半天where npx也能定位到C:\Program Files\nodejs\npx.cmd路径完全没问题。真正的问题不在 PATH而在可执行文件的类型。Windows 下的 npm 和 npx 实际是npm.cmd和npx.cmd不是npx.exe。Claude Code 的 MCP 客户端在启动子进程时底层用的是 Node.js 的child_process.spawn。spawn 在 Windows 上不会像 cmd 那样自动去解析.cmd和.bat文件的执行逻辑它只会去找真正可执行的.exe文件或者调用cmd.exe /c来包装一层。如果你给 spawn 传了npx它期望找到的是npx.exe但系统里只有npx.cmd于是直接 ENOENT。这个坑在英文社区的解决方案里几乎不会提到因为 macOS 和 Linux 上npx就是一个真正的二进制文件没有这种区别。Windows 用户照抄文档第一脚就踩进去。2.2 为什么会这样Windows 的可执行文件与 spawn稍微展开一点讲原理。Windows 操作系统中可执行文件的后缀名有严格的约定.exe才是真正能被 CreateProcess 直接拉起程序.cmd和.bat本质上是脚本需要由 cmd.exe 解释执行。当你自己在终端里输入npx时终端cmd 或 PowerShell会先找到npx.cmd然后用 cmd 的规则去执行它所以一切正常。但 Claude Code 在启动 MCP server 的时候不会走终端那套交互 shell 的逻辑而是直接调用系统 API 去创建进程。它拿到npx这个名字去 PATH 里找结果只找到了npx.cmd不符合直接执行的条件就返回 ENOENT 了。想验证这个结论很简单在 cmd 里直接运行where npx你大概率会看到一条路径指向的正是.cmd结尾的文件。这说明系统认得它但 spawn 不认。2.3 解决方案npx.cmd 与 PATH 双保险解决办法有两个我建议两个都做。第一个办法也是最直接的添加 MCP server 的时候把npx改成npx.cmd。claude mcp add playwright -- npx.cmd playwright/mcplatest这个写法等于明确告诉 spawn去执行这个.cmd文件。实际测试下来npx.cmd是可以被直接 spawn 的Claude Code 收集了命令就会正常运行。第二个办法是手动编辑配置文件把命令指定成绝对路径更稳妥。Claude Code 的 MCP 配置可以写在项目级文件比如.mcp.json或者用户级配置里。手动编辑时Windows 路径里的反斜杠记得转义{ mcpServers: { playwright: { command: C:\\Program Files\\nodejs\\npx.cmd, args: [playwright/mcplatest] } } }如果你安装 Node 时改了路径先执行where npx拿到实际路径再填进去。如果不想写绝对路径至少确保系统 PATH 里包含 Node.js 的安装目录并且使用npx.cmd这个写法。另外提一个很容易被忽略的点改完 PATH 之后已经打开的终端窗口不会自动生效必须新开一个终端再启动 Claude Code。我有一次改完 PATH 忘了重启终端又在原地折腾了十分钟属于纯笨。3. 坑二浏览器内核装不上AI 有工具也用不了第一个坑解决之后MCP server 总算从 failed 变成了 connected。我当时以为大功告成马上给 Claude 下指令“打开 example.com看看页面上有什么”。结果它调用了 browser_navigate 工具很快就返回了一段刺眼的报错browserType.launch: Executable doesnt exist at C:\Users\...\ms-playwright\chromium-XXXX\chrome-win\chrome.exe Please run npx playwright install chromium看到这个我第一反应是我不是已经装了 Playwright 吗怎么还要装后来才意识到这里说的“安装 Playwright”和“安装浏览器内核”是两码事。3.1 现象所有浏览器操作都报错从现象上看只要 AI 尝试做任何和浏览器有关的动作结果都是同一个错误找不到可执行文件。这不是因为 Playwright 库没装而是因为 Playwright 库和浏览器内核是分离的。库负责写自动化逻辑内核才是真正渲染页面、执行 JavaScript 的那个浏览器进程。npm 包 playwright/mcp 默认在启动时会尝试找你本机上对应版本的 Chromium。如果没有它就罢工。这是设计上的选择不是 bug——浏览器内核体积不小如果每个依赖 Playwright 的包都自动下载一份磁盘很快就炸了。我当时电脑上其实装过 Python 版 Playwright也跑过playwright install但 Node 生态的 Playwright 浏览器缓存索引和 Python 版的不完全互通尤其是版本号对不上的时候Node 这边依然会认为“找不到合适的浏览器”。3.2 深层原因MCP 包不内置浏览器更准确地说每个通过 npm 安装的 Playwright 相关包都对应一个具体的浏览器版本。playwright/mcp 在安装时会继承当前环境里 Playwright 库的版本并期望浏览器缓存目录里存在那个版本的内核。你用 Python 的 Playwright 装的内核版本可能不同缓存在同一个%USERPROFILE%\AppData\Local\ms-playwright目录下但目录名是按版本号区分的。Node 这边要找 chromium-XXXXPython 那边可能装的是 chromium-YYYY两者互不认账。所以解决方式不是“我装过 Playwright 了啊”而是“在 Node 环境里把当前版本对应的内核安装一遍”。在 Windows 下我建议先确保当前工作目录的 PATH 和网络环境都正常然后执行npx playwright install chromium命令执行完会去微软和 Google 等 CDN 下载几十到上百 MB 的内核文件。如果网络状况一般很容易下载到一半卡死特别是首次安装时。遇到这种问题可以配置国内的 npm 镜像同步源作为 Playwright 的下载地址。3.3 两种解法手动安装内核 / 直接调用系统 Chrome解法一就是手动安装内核上面已经写了。怕下载慢的话把环境变量指到 npmmirrorCMD 下执行set PLAYWRIGHT_DOWNLOAD_HOSThttps://cdn.npmmirror.com/binaries/playwright npx playwright install chromiumPowerShell 下执行$env:PLAYWRIGHT_DOWNLOAD_HOST https://cdn.npmmirror.com/binaries/playwright npx playwright install chromium下载完成后建议重启一下 Claude Code让 MCP server 重新启动再去测试浏览器操作。解法二更省事如果你的 Windows 系统装了 Chrome、Edge 或 Chromium 系浏览器可以让 playwright/mcp 直接使用系统浏览器省掉下载内核那一步。Edge 在 Windows 上基本是预装的用起来很稳。claude mcp add playwright -- npx.cmd playwright/mcplatest --browser chrome--browser chrome会让 Playwright 去寻找本机的 Chrome不再要求 ms-playwright 缓存目录里有对应版本的 Chromium。如果你系统里只有 Edge可以把参数写成--browser msedge。我用 Edge 试过速度和稳定性都很不错毕竟 Edge 和 Chromium 同源。注意--browser chrome参数必须加在 MCP server 的 args 里。如果你用的是之前的配置文件记得把 args 改成类似[playwright/mcplatest, --browser, chrome]。两个解法选一个就行。我自己的建议是如果电脑上有 Edge 或 Chrome直接走解法二最快如果没有就走解法一反正装一次后面都能复用。4. 坑三传输模式与端口问题配置对了还是连不上前两个坑解决之后MCP server 显示已连接浏览器内核也有了但诡异的事情出现了AI 调用某些工具的时候正常另一些工具却一直转圈到最后直接超时。更迷惑的是有一次我在 MCP server 的启动参数里加了--port 8931结果 Claude Code 彻底连不上了。这时候我才意识到传输模式这个坑比前面两个更隐蔽。4.1 三种“连接不上”的真实场景先说三种我当时遇到的真实场景。场景一Claude Code 显示 connected但 AI 一调用工具就超时日志里没有明显报错。这种情况通常是因为 MCP server 进程起来了但两边对消息的处理方式不一致或者消息卡在管道里没被正确解析。场景二我在手动测试npx playwright/mcplatest的时候为了让其他程序也能访问加了--port 8931然后还把这个参数写进了 Claude Code 的配置。结果 Claude Code 以 stdio 模式去连接一个启动在 HTTP 模式下的 server两边完全对不上自然连不上。场景三换成 HTTP/SSE 模式之后端口被其他程序占用了MCP server 启动失败Claude Code 持续显示红色摇头状态。这三类问题的根源都指向一件事Claude Code 和 playwright/mcp 之间到底用什么模式通信必须明确。4.2 stdio 与 HTTP别把两种模式混着配playwright/mcp 默认是 stdio 模式MCP server 作为一个子进程被 Claude Code 拉起双方通过标准输入输出流一条一条交换 JSON-RPC 消息。这个模式不需要端口不占网络资源也不存在局域网暴露的问题是本机使用最合理的选择。如果你手动执行 playwright/mcp 命令行工具什么都不加它就是用 stdio 模式。Claude Code 的claude mcp add默认添加的也是 stdio server。只有当你指定--port参数时playwright/mcp 才会切换成 HTTP 模式监听一个本地端口等着客户端通过 HTTP 请求来连。此时 Claude Code 那边应该用--transport http加 URL 的方式注册而不是默认的 stdio 方式。手动编辑配置时stdio 模式对应的配置是{ mcpServers: { playwright: { command: npx.cmd, args: [playwright/mcplatest] } } }如果你偏要用 HTTP 模式那配置应该长这样不同版本字段名会有细微差异{ mcpServers: { playwright: { type: http, url: http://127.0.0.1:8931/mcp } } }这里最容易犯的错就是混着配command 和 args 都写了还加了一个type: http或者后来把 URL 也写上。结果 Claude Code 内部就晕了到底该走子进程还是该访问 URL状态一直表现为 failed 或超时。我在这一步反复删了加、加了删最后才反应过来文档里写的是“二选一”不是“都写上”。提示在本机日常使用强烈建议用 stdio 模式也就是不要加--port保持默认。HTTP 模式适合 MCP server 独立部署、或者局域网远程连接这种真正的服务化场景。另外如果你因为某种原因开了 HTTP 模式务必确认端口只绑定 127.0.0.1不要绑 0.0.0.0。MCP server 可以控制浏览器等于一个没有鉴权的远程控制接口暴露出去非常危险。4.3 端口占用排查与 UTF-8 编码保护如果你确实要用 HTTP 模式端口 8931 是我随便举例用的实际选个没被占用的端口就行。Windows 下查端口占用很简单netstat -ano | findstr 8931如果结果里有 LISTENING 状态且不是你预期的进程用tasklist | findstr PID号看是哪个程序占着然后去任务管理器结束它或者换个端口重新启动。还有一种 Windows 特有的坑需要单独说编码。这个坑在中文系统上特别容易出现尤其是当你的 Windows 系统语言是中文默认代码页是 936GBK而 MCP 协议本身要求 UTF-8 编码的 JSON-RPC 消息。如果 Claude Code 和 playwright/mcp 之间传的中文消息以 GBK 字节流出接收方按 UTF-8 解析轻则日志乱码重则直接导致协议层消息解析失败。症状就是MCP server 明明起来了但 Claude Code 那边始终收不到有效响应工具调用一直卡住。有效的处理办法有两种。一是在启动 Claude Code 之前的终端里执行chcp 65001把代码页切到 UTF-8再启动claude。二是在 Windows 设置里勾选“使用 Unicode UTF-8 提供全球语言支持”一劳永逸不过需要重启。对于大部分只想快速跑通的人来说推荐直接用chcp 65001副作用最小。5. 一次跑通的完整配置流程Windows 11 实测三个坑都说完了但光知道坑不够还得给一套能直接照抄的流程。下面这套配置是我在 Windows 11 上实际跑通的目标是让 Claude Code 能通过 Playwright MCP 打开浏览器、访问页面、截图、读取页面内容。整个过程大约十分钟。5.1 环境准备清单开始之前确认三件事Node.js 版本不低于 18推荐 20 LTS。命令行检查node -v。Claude Code 已安装并能正常启动。命令行检查claude --version。磁盘剩余空间不少于 2GB浏览器内核要占几百 MB。如果你电脑上有 Chrome 或 Edge流程会少一步。没有的话也不碍事后面装内核就行。5.2 添加 MCP 并验证连接第一种情况用系统 Chrome。claude mcp add playwright -- npx.cmd playwright/mcplatest --browser chrome第二种情况没有 Chrome想用 Playwright 自带的 Chromium 内核先装内核再添加 MCP。npx playwright install chromium claude mcp add playwright -- npx.cmd playwright/mcplatest添加完执行claude mcp list看到 playwright 那一行的状态不是 failed说明注册这一步过了。如果显示 disconnected回看第 2 章的内容检查是不是又写成npx没写npx.cmd。然后启动 Claude Code 会话输入/mcp正常情况下playwright 会出现在已连接列表里。如果这里显示没有连接先用claude mcp remove playwright删掉再重新添加别直接在配置里手动改很容易改乱。5.3 用一个真实任务测试端到端链路命令行验证通过后在 Claude Code 里提一个简单任务“使用 playwright 打开 https://example.com截取页面截图保存到当前目录并告诉我页面标题。”我实测的时候Claude 会先调用 browser_navigate 打开页面再调用 browser_snapshot 获取页面结构最后调用 browser_screenshot 保存图片。如果你的配置正确这个过程通常不会超过 30 秒。如果它说“没有找到截图工具”怀疑是传输模式配置错了回到第 4 章检查。任务完成后当前目录下会多一个 PNG 图片文件打开确认内容是不是 example.com 的页面。页面上那一行经典的 “Example Domain” 能被 AI 读取出来就说明整条链路已经通了。注意我推荐用 example.com 这种完全中立的测试站点避免访问不稳定的外部服务导致误判。先把链路跑通再让它去操作你真正要测的网站。5.4 常见失败时的回滚技巧如果中途改坏了配置最稳妥的做法不是手动编辑 JSON而是用 Claude Code 自己的命令删掉重加claude mcp remove playwright claude mcp add playwright -- npx.cmd playwright/mcplatest删除之前可以在claude mcp list里看一眼当前的配置详情。如果连 list 都出不来多半是 JSON 语法坏了去项目目录或用户目录找.mcp.json和~/.claude.json备份一份之后把关于 playwright 的段落删掉再重新添加。6. 常见问题速查与经验总结这段时间过来我把 Windows 上配置 Playwright MCP 的问题整理成一个速查表。以后再遇到类似情况直接按表排查速度会快很多。6.1 问题速查表症状可能原因解决方法spawn npx ENOENTMCP 一直 disconnectedWindows 下 npx 是 .cmdspawn 找不到把 npx 改成 npx.cmd或用 where npx 取绝对路径浏览器操作报 Executable doesnt existplaywright/mcp 默认不含浏览器内核执行 npx playwright install chromium或用 --browser chrome/msedge 调用系统浏览器下载 chromium 卡住或失败网络访问 CDN 不稳定设置 PLAYWRIGHT_DOWNLOAD_HOST 为国内镜像源重新执行 installMCP server 已连接但工具调用一直超时stdio 模式与 HTTP 模式混配或编码问题去掉 --port 参数保持 stdio在终端执行 chcp 65001 切到 UTF-8端口启动失败提示地址被占用HTTP 模式下端口被其他程序占用用 netstat -ano 查找占用进程结束进程或换端口中文日志乱码协议消息异常中文 Windows 默认 GBK 代码页chcp 65001或在系统设置里开启 UTF-8 Beta 选项修改配置后仍然失败手动改 JSON 导致语法或结构错误用 claude mcp remove 删除后重新添加不要手硬改6.2 个人使用体会与建议Windows 下做浏览器自动化这件事这几年其实已经很成熟了Playwright 官方对 Windows 的支持本来就不差。真正让人头疼的往往不是框架本身而是环境细节。比如 .cmd 文件、代码页、PATH 不生效、端口占用它们单个看起来都不难叠在一起就特别容易让人崩溃。我自己跑通之后最大的体会是不要拿着一份 macOS 的教程在 Windows 上无脑复制。遇到报错先看 Clade Code 的 debug 日志MCP server 这层出了问题日志里多半有明确线索。其次能用命令行完成的操作不要手动编辑 JSON降低出错概率。最后先把简单场景跑通再叠加复杂度不要一上来就让 AI 操作一个登录后才能访问的站点那样即使失败了你也分不清是 MCP 的问题还是目标网站的问题。如果后续你想玩更深一点我建议试试这几个方向用 screenshot 做视觉回归对比用 browser_snapshot 让 AI 理解动态页面的结构或者把 playwright/mcp 跑在固定端口上让多个 Claude Code 会话共享同一个浏览器控制服务。每个方向都有各自的坑但基于现在这条已经跑通的链路探索起来会轻松很多。
