最近在 Windows 上折腾 Claude Code想给它配上 Playwright MCP让这个编程助手能直接“看见”浏览器、操作页面。想法很美好过程却是实打实的折磨。整整一下午我撞了三个大坑每个坑都浪费了不少时间。先给没接触过的朋友说下背景。Claude Code 是 Anthropic 出的命令行编程助手跑在终端里能读代码、改文件、跑命令。MCP 全称 Model Context Protocol是 Claude 连接外部工具的标准协议可以简单理解成给 AI 插上各种外设。Playwright MCP 就是微软官方提供的一个 MCP 服务装上之后Claude Code 就能驱动真实浏览器做自动化测试、网页调试、数据抽取这类操作。这套组合最大的价值在于它把“自然语言指令”和“真实浏览器操作”打通了。比如你跟它说“打开百度搜索 Claude Code把前三条结果的标题和链接抓出来”它会自己控制浏览器完成不用你手写一行 Playwright 脚本。对偏前端的开发者、自动化测试工程师、以及经常要抓网页信息的人来说实用性直接拉满。前提是你能在 Windows 上把它跑起来。我这次踩坑的整个过程从环境准备到最终跑通前后花了几个小时。下面我把这三个坑一个一个拆开讲每个都附上原因分析和解决办法希望你能绕过去。1. 环境准备先搞清楚这套体系的基本构成动手之前我先把整套链路理了一遍。Windows 下要让 Claude Code 用上 Playwright MCP通常有这么几个环节Node.js 环境、Claude Code 本体、MCP 配置文件以及 Playwright 需要的浏览器内核。任何一个环节出问题后面都会跟着报错。1.1 基础环境Node.js 千万别装老版本Playwright MCP 是一个基于 Node.js 的包官方名叫playwright/mcp通过 npx 命令启动。所以 Node.js 是第一个必须装的组件。国内很多教程会让你装 Node 18但实测下来playwright/mcp新版对 Node 版本有隐性的要求太低的话运行时会报各种奇怪的错。我一开始机器上是 Node 16装好 Claude Code 之后配 MCP跑npx playwright/mcplatest直接报语法错误根本起不来。后来查了官方文档发现要求 Node 18 以上Recommended 区域甚至建议 Node 20。我把 Node 升级到 22 LTS 之后世界瞬间清净了。这里有个小提示Windows 下升级 Node 不要直接覆盖安装容易留残留文件。建议先把旧版本彻底卸载再装新版。装完在 PowerShell 里执行node -v确认版本号没问题再继续。1.2 安装 Claude Codenpm 方式最省心Claude Code 本身安装很简单一行命令npm install -g anthropic-ai/claude-code装完后在终端里运行claude会进入交互式界面第一次会要求你登录账号并授权。我建议配置这个过程用官方默认方式就好了这里不涉及什么额外操作。需要提醒的是Windows 下 Claude Code 依赖终端环境PowerShell 和 CMD 都支持但如果你用的是 Windows Terminal 里嵌的 Git Bash有时候会有兼容性问题建议直接用 PowerShell 或 CMD 跑 Claude Code。我最初用 Git Bash 试了下MCP 服务的启动方式有细微差异容易踩到第二个坑。1.3 MCP 的调用链路Claude Code 是怎么找到 Playwright 的理解这条链路很重要后面排查的时候全靠它了。MCP 的架构分三端MCP Host宿主、MCP Server服务端和工具提供方。这里Claude Code 是 Hostplaywright/mcp是 Server浏览器内核是最终干活的人。Claude Code 启动时会读取 MCP 配置文件里面写着每个 Server 应该如何启动用什么命令、带什么参数。然后 Claude Code 通过标准输入输出stdio或者 HTTP 与 Server 通信把自然语言请求转换成工具调用指令发给 ServerServer 再驱动浏览器执行。用生活场景类比Claude Code 是老板Playwright MCP 是执行助理浏览器是员工。老板把意图告诉助理助理安排员工干活员工的结果再一层层上报。所以任何一个环节断了效果都会打折扣。这个链路意味着配置 MCP 的核心就是“告诉 Claude Code 怎么启动 Playwright MCP 这个助理”。Windows 下的第一个坑恰好就出在这个“怎么启动”上。2. 坑一配置格式对了但服务就是起不来先说第一个坑也是我最先撞上的MCP 配置写完了但 Claude Code 一直报连接失败甚至根本不识别这个 Server。2.1 错误现象配置文件里写了但工具列表里没有我用 Claude Code 的交互界面输入/mcp查看已连接的服务器列表是空的。检查配置文件明明已经添加了 playwright 的配置。后来我直接在命令行里敲claude mcp list查看才发现配置虽然存在但状态显示错误后面的日志提示无法启动进程。这时候我去翻配置文件发现一个很典型的低级错误——我把 MCP 服务器的参数写错了类型。规范的配置应该是claude mcp add --scope user playwright -- npx playwright/mcplatest或者手动在配置文件里写入{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }注意args是一个字符串数组。我第一次偷懒把它写成了这样{ args: playwright/mcplatest }这就是一个字符串了不是数组。Claude Code 去解析的时候没法把它拆成命令行参数直接启动失败。这是一种很典型的“看着像没问题实际上是错的”情况。还有一种情况Windows 的路径分隔符是反斜杠\如果command你填了绝对路径比如C:\Users\xxx\AppData\Roaming\npm\npx.cmd在 JSON 里反斜杠是转义字符必须写成C:\\Users\\xxx\\AppData\\Roaming\\npm\\npx.cmd才能被正确解析。我第一次踩这个坑后总结了教训像这类配置优先用claude mcp add命令自动生成不要手动改 JSON。2.2 解决方案学会用官方命令而不是手动改文件在 Windows 上配置 MCP推荐用命令行方式因为它会自动处理路径转义、传递参数这些麻烦事。具体操作如下claude mcp add --scope user playwright -- npx playwright/mcplatest这条命令把 playwright 注册到当前用户的 MCP 配置里启动方式是npx playwright/mcplatest。如果后面要加参数比如指定浏览器就接着写claude mcp add --scope user playwright -- npx playwright/mcplatest --browser chromium--前面的部分是 Claude Code 的参数后面的是要交给 MCP Server 的启动参数。配置完之后用claude mcp list确认一下子项状态。正常会显示类似✔ playwright - npx playwright/mcplatest (stdio)如果你看到的是红叉或者错误提示说明启动有问题直接看错误信息排查。2.3 手动改配置文件时要注意的细节如果你确实需要手动编辑配置文件比如要改某个 Server 的参数Windows 下配置文件路径一般在这里C:\Users\[你的用户名]\.claude.json用记事本打开后找到mcpServers对象修改对应的 Server 配置。这里有几个经验command建议直接写npx不要写npx.cmd或者绝对路径。Claude Code 在 Windows 下默认会用系统 PATH 找到 npx写全路径反而容易因为 JSON 转义问题出错。args必须是数组每个参数一个元素不要让 Clauede Code 自己去拆分否则分分钟出错。配置改完必须重启 Claude Code 才会生效直接在交互界面里输入/mcp刷新也不行要退出重进。第一个坑解决后我满心欢喜地继续测试结果马上就撞上了第二个坑。3. 坑二PowerShell 环境和 npx 的那点糟心事第二个坑出现在 Windows 特有的环境问题上。配置看起来完全正确但 MCP Server 就是启动不了错误信息要么是“权限被拒绝”要么是“无法加载文件”。3.1 错误现象启动 npx 时报执行策略错误我测试 Playwright MCP 单独运行时直接在 PowerShell 里敲npx playwright/mcplatest结果报了一个很经典的错无法加载文件 C:\Users\xxx\AppData\Roaming\npm\npx.ps1因为在此系统上禁止运行脚本。这是 Windows PowerShell 的执行策略Execution Policy在搞鬼。PowerShell 默认禁止运行本地脚本文件而 npm 在安装全局包时生成的npx.ps1刚好是一个脚本文件。Claude Code 在调用 MCP Server 时如果它选择用 PowerShell 作为启动环境就会触发这个限制。我当时第一反应是 Claude Code 的配置有问题但其实问题出在系统环境和启动方式上。3.2 原因分析PowerShell 执行策略和路径两边起火这里要解释一下 Windows 的执行策略。它有几个等级Restricted默认禁止所有脚本、RemoteSigned本地脚本可运行远程脚本需签名Windows 客户端默认就是它、Unrestricted所有脚本可运行、Bypass临时绕过。如果你从来没动过那 PowerShell 上基本是 Restricted 或 RemoteSigned导致 npx.ps1 跑不了。但是Claude Code 在 Windows 上启动 MCP Server 时到底用的什么解释器这个我实际测下来发现它走的是 CMD按理说不会读 PowerShell 的策略。那为什么还会踩到这个坑问题出在两个地方。一是我在测试时Claude Code 内部可能有套娃逻辑某些操作走了 PowerShell。二是我配置的时候把command直接写成了npx但在 CMD 下npx指向的是npx.cmd如果在某些场景下解析到了npx.ps1就会撞上执行策略。还有一个朋友遇到过更离谱的情况他把 Claude Code 装进了 Git Bash 的 PATH 里然后在 Git Bash 里运行导致 MCP 的启动脚本被解释成了 Bash 脚本一堆语法错误。3.3 解决方案三种方式绕开 PowerShell 限制最简单的方法改 PowerShell 执行策略把限制放宽。管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令只对当前用户生效比较安全。执行完再跑npx playwright/mcplatest验证。第二种方案在 Claude Code 的 MCP 配置里把启动命令从npx改成cmd /c npx。这样 Clauede Code 会强制用 CMD 去启动 npx走的是npx.cmd不涉及 PowerShell 脚本。配置命令是claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest第三种方案干脆不用 npx把playwright/mcp全局安装然后直接调用它的入口文件。npm install -g playwright/mcp然后用claude mcp add --scope user playwright -- playwright-mcp这样就不用通过 npx 去动态拉包了少一层解析也就少一处出问题。我最后采用的是第二种方案cmd /c npx的方式最稳既不用动系统策略又能避免 PowerShell 的坑。不过这里要注意加了cmd /c之后如果还要传参数给 playwright格式就得写成claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --browser chromium注意到没参数前面补了一个符号。这是因为 Claude Code 的--后面的内容会原样传给 Server但如果你通过cmd /c启动参数解析规则会变需要把参数用前缀包一层才能正确传到 npx。这个细节非常坑我也是试了三次才试出来。3.4 顺手验证 Node 版本第三个隐蔽问题如果 Node 版本太老MCP Server 本身可能起不来。执行策略搞定之后我单独跑npx playwright/mcplatest时又遇到了Node.js v16 is not supported的报错这时候才回头检查 Node 版本发现自己机器上还是老的 16。所以把 Node 升级到 20 或 22 LTS是 Windows 下配置这套组合的必要条件。别心疼那点升级时间一次性整利索后面少受罪。到这一步配置层面的坑算是填平了。但别急着欢呼真正跑起来之后还有一个更隐蔽的坑等着我。4. 坑三浏览器启动失败Claude Code 说没找到引擎配置和服务都正常后我以为大功告成结果一上来就让 Claude Code 打开一个网页它居然告诉我没有可用的浏览器实例。这第三个坑出在 Playwright 的浏览器内核上。4.1 错误现象MCP Server 启动成功但打不开页面Claude Code 跟 MCP Server 的连接已经建立了/mcp里能看到 playwright 的状态是正常的。但只要一调用浏览器相关的工具就报错说 Executable doesnt exist或者找不到 Chrome/Chromium 的可执行文件。这个原因不复杂playwright/mcp只是一个控制层它默认要求系统里安装了对应的浏览器内核。很多教程会告诉你装完 MCP 就算完事了但 Windows 上 Playwright 不会自动帮你下载 Chromium需要手动跑一条命令。4.2 解决方案安装 Playwright 浏览器内核在命令行里执行npx playwright install chromium或者你想让它用系统已有的 Chrome 或者 Edge可以执行npx playwright install msedge安装时间取决于网速几 MB 到一百多 MB 不等。装完后再测试Claude Code 就能顺利打开网页了。这里有个差异化建议如果你想做的是抓取页面、跑自动化测试建议装 Chromium如果你是做前端调试想让它操作你正在开发的那个浏览器可以考虑直接让它连接到已有的 Chrome 实例用--channel chrome参数。4.3 深层问题Windows 下的浏览器选用策略还有一个点值得展开。Playwright MCP 在 Windows 下默认使用 Chromium 的无头模式headless也就是没有界面窗口。这样做的好处是节省资源行为也更稳定但对于初次调试的人来说很痛苦——你看不到它在干什么。如果想让 Claude Code 操作时弹出真实的浏览器窗口方便观察可以给 MCP Server 加启动参数claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --headlessfalse这里依然要沿用前缀的写法不然参数传不进去。加了--headlessfalse之后每次 Claude Code 操作浏览器时你都能看到窗口一闪一闪地完成点击、滚动、输入特别直观。还有一个 Windows 特有的问题如果你装的是精简版系统系统里可能同时缺这缺那。Playwright 的浏览器在 Windows 上依赖一些 WebView2 运行时、Media Foundation 组件。缺了之后报错信息会指向某个 dll 文件找不到。这种问题安装 WebView2 Runtime 一般就能解决微软官网直接下就行。顺带提一下如果之前装过老版本的 Playwright可能会残留旧的内核建议在跑npx playwright install chromium之前先执行npx playwright install --list查看当前状态。4.4 小技巧用本机 Edge 代替下载 Chromium如果你不想下载几百 MB 的 Chromium有一个省事的办法Windows 系统自带 Edge 浏览器Playwright 支持直接驱动 Edge。配置方式claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --browser msedge --headlessfalse实测下来用系统 Edge 既省了下载时间页面兼容性也更好。唯一的注意点是如果你的 Edge 正在工作被 Playwright 接管后行为可能有点怪最好先关闭正在使用的窗口。这个坑填完之后整条链路终于通了。我让 Claude Code 打开一个网页顺利抓到了页面标题和正文。5. 排错工具箱再遇到问题怎么自己排查三个坑讲完了但说实话每个人的环境差异很大你遇到的报错大概率和我举的例子不完全一样。这里我把排查 MCP 问题的通用思路整理出来了照着顺序检查能少走很多弯路。5.1 最常用的三条诊断命令Claude Code 自带 MCP 诊断命令在终端里跑claude mcp list列出所有已注册的 MCP Server以及它们的连接状态。这个命令能快速告诉你 Server 是否正常启动。如果某个 Server 状态异常接着跑claude mcp get playwright查看单个 Server 的详细配置确认 command 和 args 是否符合预期。如果配置没问题但还是启动不了直接看详细日志claude --debug用调试模式启动 Claude Code它会把每次 MCP 通信的细节打印出来包括启动命令行、退出码、错误输出。这是我这次排查最依赖的工具。5.2 绕过 Claude Code直接测试 MCP Server很多时候MCP 出问题不一定是 Claude Code 的锅而是 Server 本身起不来。这时候别急着在 Claude Code 里反复试先在命令行里手动起一次 Server看它能不能跑。npx playwright/mcplatest如果这条命令在终端里能正常运行、没有任何报错、进程一直挂在那里说明 Server 本身是好的问题出在 Claude Code 和 Server 之间的连接方式。如果这条命令本身就报错那方向就清晰了解决这个报错就好。用这个思路我把问题从“Claude Code 为什么连不上”简化成了“npx 为什么跑不起来”一下就定位到了 PowerShell 执行策略的问题。5.3 Windows 环境特有的几个隐藏坑整理这次经验时我总结了几个 Windows 特有但很少被教程提及的坑杀毒软件和 Windows Defender 的实时防护偶尔会拦截npx从临时目录拉取 package导致下载失败或卡住。如果发现安装超时先把 Defender 的“基于声誉的保护”临时关掉装完再开。不要给 Node.js 和 Claude Code 的安装目录加中文或空格的路径。我见过有人把 npm 全局路径配到C:\Program Files\nodejs\node_cache结果 npx 启动 MCP 时参数解析直接错乱。如果你的系统用户名是中文Claude Code 的配置文件路径里会出现中文目录有些第三方终端可能解析异常。遇到类似情况检查一下%USERPROFILE%路径下能否正常访问。多个版本的 Node 共存时比如通过 nvm-windows 管理Claude Code 启动时可能选错 Node 版本导致 MCP Server 运行在旧版 Node 上。建议用nvm current确认当前版本再启动 Claude Code。6. 跑通之后这套组合能干什么配置跑通之后我实际测了几个场景真实感受就一个字值。6.1 场景一让 Claude Code 抓取页面内容我让它“打开一个页面把页面标题、正文前两段和所有 h2 标题提取出来”它自动打开浏览器等待页面加载完然后提取对应元素再按 markdown 格式输出。整个过程没有任何人工干预。这种能力对做竞品分析、资料收集的人来说非常实用。以前要自己写爬虫或者复制粘贴现在直接用自然语言描述需求它就帮你做了。6.2 场景二自动化测试一个登录流程我拿一个内部系统做测试跟 Claude Code 说“打开登录页输入测试账号密码点击登录告诉我页面是否跳转成功”。它会自动定位输入框、填写内容、点击按钮、判断跳转结果。对测试工程师来说这套组合的潜力在于可以把“写自动化测试脚本”和“执行自动化测试”这两件事合并成一句自然语言。当然真正落地到 CI/CD 还需要不少改造但至少日常验证流程已经足够了。6.3 场景三页面交互和调试前端开发者会喜欢这个场景让 Claude Code 打开某个页面点击某个按钮再告诉你控制台有没有报错。它可以通过 Playwright 监听浏览器的 console 消息和网络请求把信息回传给你。我试过让它“打开本地开发服务器点击导航栏的第三个按钮把 Network 面板里所有请求的 URL 和状态码列出来”它做得挺漂亮省去了我手动打开 DevTools 的功夫。6.4 潜在扩展方向这套组合的扩展空间很大。Playwright 本身支持多浏览器、多标签页、页面截图、PDF 导出、文件下载这些能力 MCP 协议全覆盖了。你可以让 Claude Code 定时截图、批量跑回归用例甚至对接它生成测试报告。我个人的下一个计划是把这套配置接入到日常的自动化巡检流程里让 Claude Code 每天定时打开几个重点页面检查可用性和关键信息有问题就在群里通知。实现思路基本清晰就看实际跑起来有没有坑了。7. 最后聊点心得回头再看这次折腾三个坑分别踩在配置格式、系统环境和浏览器内核上基本覆盖了 Windows 下配置 MCP 的典型雷区。第一个坑是知识盲区第二个坑是系统特性第三个坑是文档不全。每个坑单独拎出来都不难难的是串在一条链路里报错又不会明确告诉你根因在哪。如果你也在 Windows 上配置 Claude Code Playwright MCP我的核心建议只有三条第一Node 版本升到 20 以上第二启动命令用cmd /c npx ...格式绕开 PowerShell第三别忘装浏览器内核。三条全中基本十分钟就能跑通。最后再分享一个小技巧遇到 MCP 配置问题先把 Claude Code 的 debug 日志打开然后强行在命令行列 MCP Server 的启动命令手动跑一遍这两个动作能帮你把问题缩小到“配置错误”还是“环境错误”。我这次如果不是靠这个思路恐怕还要多折腾几个小时。 
长河君 · 2026/10/17 16:53:12 · 阅读 1.2k Windows下Claude Code与Playwright MCP配置避坑指南
最近在 Windows 上折腾 Claude Code想给它配上 Playwright MCP让这个编程助手能直接“看见”浏览器、操作页面。想法很美好过程却是实打实的折磨。整整一下午我撞了三个大坑每个坑都浪费了不少时间。先给没接触过的朋友说下背景。Claude Code 是 Anthropic 出的命令行编程助手跑在终端里能读代码、改文件、跑命令。MCP 全称 Model Context Protocol是 Claude 连接外部工具的标准协议可以简单理解成给 AI 插上各种外设。Playwright MCP 就是微软官方提供的一个 MCP 服务装上之后Claude Code 就能驱动真实浏览器做自动化测试、网页调试、数据抽取这类操作。这套组合最大的价值在于它把“自然语言指令”和“真实浏览器操作”打通了。比如你跟它说“打开百度搜索 Claude Code把前三条结果的标题和链接抓出来”它会自己控制浏览器完成不用你手写一行 Playwright 脚本。对偏前端的开发者、自动化测试工程师、以及经常要抓网页信息的人来说实用性直接拉满。前提是你能在 Windows 上把它跑起来。我这次踩坑的整个过程从环境准备到最终跑通前后花了几个小时。下面我把这三个坑一个一个拆开讲每个都附上原因分析和解决办法希望你能绕过去。1. 环境准备先搞清楚这套体系的基本构成动手之前我先把整套链路理了一遍。Windows 下要让 Claude Code 用上 Playwright MCP通常有这么几个环节Node.js 环境、Claude Code 本体、MCP 配置文件以及 Playwright 需要的浏览器内核。任何一个环节出问题后面都会跟着报错。1.1 基础环境Node.js 千万别装老版本Playwright MCP 是一个基于 Node.js 的包官方名叫playwright/mcp通过 npx 命令启动。所以 Node.js 是第一个必须装的组件。国内很多教程会让你装 Node 18但实测下来playwright/mcp新版对 Node 版本有隐性的要求太低的话运行时会报各种奇怪的错。我一开始机器上是 Node 16装好 Claude Code 之后配 MCP跑npx playwright/mcplatest直接报语法错误根本起不来。后来查了官方文档发现要求 Node 18 以上Recommended 区域甚至建议 Node 20。我把 Node 升级到 22 LTS 之后世界瞬间清净了。这里有个小提示Windows 下升级 Node 不要直接覆盖安装容易留残留文件。建议先把旧版本彻底卸载再装新版。装完在 PowerShell 里执行node -v确认版本号没问题再继续。1.2 安装 Claude Codenpm 方式最省心Claude Code 本身安装很简单一行命令npm install -g anthropic-ai/claude-code装完后在终端里运行claude会进入交互式界面第一次会要求你登录账号并授权。我建议配置这个过程用官方默认方式就好了这里不涉及什么额外操作。需要提醒的是Windows 下 Claude Code 依赖终端环境PowerShell 和 CMD 都支持但如果你用的是 Windows Terminal 里嵌的 Git Bash有时候会有兼容性问题建议直接用 PowerShell 或 CMD 跑 Claude Code。我最初用 Git Bash 试了下MCP 服务的启动方式有细微差异容易踩到第二个坑。1.3 MCP 的调用链路Claude Code 是怎么找到 Playwright 的理解这条链路很重要后面排查的时候全靠它了。MCP 的架构分三端MCP Host宿主、MCP Server服务端和工具提供方。这里Claude Code 是 Hostplaywright/mcp是 Server浏览器内核是最终干活的人。Claude Code 启动时会读取 MCP 配置文件里面写着每个 Server 应该如何启动用什么命令、带什么参数。然后 Claude Code 通过标准输入输出stdio或者 HTTP 与 Server 通信把自然语言请求转换成工具调用指令发给 ServerServer 再驱动浏览器执行。用生活场景类比Claude Code 是老板Playwright MCP 是执行助理浏览器是员工。老板把意图告诉助理助理安排员工干活员工的结果再一层层上报。所以任何一个环节断了效果都会打折扣。这个链路意味着配置 MCP 的核心就是“告诉 Claude Code 怎么启动 Playwright MCP 这个助理”。Windows 下的第一个坑恰好就出在这个“怎么启动”上。2. 坑一配置格式对了但服务就是起不来先说第一个坑也是我最先撞上的MCP 配置写完了但 Claude Code 一直报连接失败甚至根本不识别这个 Server。2.1 错误现象配置文件里写了但工具列表里没有我用 Claude Code 的交互界面输入/mcp查看已连接的服务器列表是空的。检查配置文件明明已经添加了 playwright 的配置。后来我直接在命令行里敲claude mcp list查看才发现配置虽然存在但状态显示错误后面的日志提示无法启动进程。这时候我去翻配置文件发现一个很典型的低级错误——我把 MCP 服务器的参数写错了类型。规范的配置应该是claude mcp add --scope user playwright -- npx playwright/mcplatest或者手动在配置文件里写入{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }注意args是一个字符串数组。我第一次偷懒把它写成了这样{ args: playwright/mcplatest }这就是一个字符串了不是数组。Claude Code 去解析的时候没法把它拆成命令行参数直接启动失败。这是一种很典型的“看着像没问题实际上是错的”情况。还有一种情况Windows 的路径分隔符是反斜杠\如果command你填了绝对路径比如C:\Users\xxx\AppData\Roaming\npm\npx.cmd在 JSON 里反斜杠是转义字符必须写成C:\\Users\\xxx\\AppData\\Roaming\\npm\\npx.cmd才能被正确解析。我第一次踩这个坑后总结了教训像这类配置优先用claude mcp add命令自动生成不要手动改 JSON。2.2 解决方案学会用官方命令而不是手动改文件在 Windows 上配置 MCP推荐用命令行方式因为它会自动处理路径转义、传递参数这些麻烦事。具体操作如下claude mcp add --scope user playwright -- npx playwright/mcplatest这条命令把 playwright 注册到当前用户的 MCP 配置里启动方式是npx playwright/mcplatest。如果后面要加参数比如指定浏览器就接着写claude mcp add --scope user playwright -- npx playwright/mcplatest --browser chromium--前面的部分是 Claude Code 的参数后面的是要交给 MCP Server 的启动参数。配置完之后用claude mcp list确认一下子项状态。正常会显示类似✔ playwright - npx playwright/mcplatest (stdio)如果你看到的是红叉或者错误提示说明启动有问题直接看错误信息排查。2.3 手动改配置文件时要注意的细节如果你确实需要手动编辑配置文件比如要改某个 Server 的参数Windows 下配置文件路径一般在这里C:\Users\[你的用户名]\.claude.json用记事本打开后找到mcpServers对象修改对应的 Server 配置。这里有几个经验command建议直接写npx不要写npx.cmd或者绝对路径。Claude Code 在 Windows 下默认会用系统 PATH 找到 npx写全路径反而容易因为 JSON 转义问题出错。args必须是数组每个参数一个元素不要让 Clauede Code 自己去拆分否则分分钟出错。配置改完必须重启 Claude Code 才会生效直接在交互界面里输入/mcp刷新也不行要退出重进。第一个坑解决后我满心欢喜地继续测试结果马上就撞上了第二个坑。3. 坑二PowerShell 环境和 npx 的那点糟心事第二个坑出现在 Windows 特有的环境问题上。配置看起来完全正确但 MCP Server 就是启动不了错误信息要么是“权限被拒绝”要么是“无法加载文件”。3.1 错误现象启动 npx 时报执行策略错误我测试 Playwright MCP 单独运行时直接在 PowerShell 里敲npx playwright/mcplatest结果报了一个很经典的错无法加载文件 C:\Users\xxx\AppData\Roaming\npm\npx.ps1因为在此系统上禁止运行脚本。这是 Windows PowerShell 的执行策略Execution Policy在搞鬼。PowerShell 默认禁止运行本地脚本文件而 npm 在安装全局包时生成的npx.ps1刚好是一个脚本文件。Claude Code 在调用 MCP Server 时如果它选择用 PowerShell 作为启动环境就会触发这个限制。我当时第一反应是 Claude Code 的配置有问题但其实问题出在系统环境和启动方式上。3.2 原因分析PowerShell 执行策略和路径两边起火这里要解释一下 Windows 的执行策略。它有几个等级Restricted默认禁止所有脚本、RemoteSigned本地脚本可运行远程脚本需签名Windows 客户端默认就是它、Unrestricted所有脚本可运行、Bypass临时绕过。如果你从来没动过那 PowerShell 上基本是 Restricted 或 RemoteSigned导致 npx.ps1 跑不了。但是Claude Code 在 Windows 上启动 MCP Server 时到底用的什么解释器这个我实际测下来发现它走的是 CMD按理说不会读 PowerShell 的策略。那为什么还会踩到这个坑问题出在两个地方。一是我在测试时Claude Code 内部可能有套娃逻辑某些操作走了 PowerShell。二是我配置的时候把command直接写成了npx但在 CMD 下npx指向的是npx.cmd如果在某些场景下解析到了npx.ps1就会撞上执行策略。还有一个朋友遇到过更离谱的情况他把 Claude Code 装进了 Git Bash 的 PATH 里然后在 Git Bash 里运行导致 MCP 的启动脚本被解释成了 Bash 脚本一堆语法错误。3.3 解决方案三种方式绕开 PowerShell 限制最简单的方法改 PowerShell 执行策略把限制放宽。管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令只对当前用户生效比较安全。执行完再跑npx playwright/mcplatest验证。第二种方案在 Claude Code 的 MCP 配置里把启动命令从npx改成cmd /c npx。这样 Clauede Code 会强制用 CMD 去启动 npx走的是npx.cmd不涉及 PowerShell 脚本。配置命令是claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest第三种方案干脆不用 npx把playwright/mcp全局安装然后直接调用它的入口文件。npm install -g playwright/mcp然后用claude mcp add --scope user playwright -- playwright-mcp这样就不用通过 npx 去动态拉包了少一层解析也就少一处出问题。我最后采用的是第二种方案cmd /c npx的方式最稳既不用动系统策略又能避免 PowerShell 的坑。不过这里要注意加了cmd /c之后如果还要传参数给 playwright格式就得写成claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --browser chromium注意到没参数前面补了一个符号。这是因为 Claude Code 的--后面的内容会原样传给 Server但如果你通过cmd /c启动参数解析规则会变需要把参数用前缀包一层才能正确传到 npx。这个细节非常坑我也是试了三次才试出来。3.4 顺手验证 Node 版本第三个隐蔽问题如果 Node 版本太老MCP Server 本身可能起不来。执行策略搞定之后我单独跑npx playwright/mcplatest时又遇到了Node.js v16 is not supported的报错这时候才回头检查 Node 版本发现自己机器上还是老的 16。所以把 Node 升级到 20 或 22 LTS是 Windows 下配置这套组合的必要条件。别心疼那点升级时间一次性整利索后面少受罪。到这一步配置层面的坑算是填平了。但别急着欢呼真正跑起来之后还有一个更隐蔽的坑等着我。4. 坑三浏览器启动失败Claude Code 说没找到引擎配置和服务都正常后我以为大功告成结果一上来就让 Claude Code 打开一个网页它居然告诉我没有可用的浏览器实例。这第三个坑出在 Playwright 的浏览器内核上。4.1 错误现象MCP Server 启动成功但打不开页面Claude Code 跟 MCP Server 的连接已经建立了/mcp里能看到 playwright 的状态是正常的。但只要一调用浏览器相关的工具就报错说 Executable doesnt exist或者找不到 Chrome/Chromium 的可执行文件。这个原因不复杂playwright/mcp只是一个控制层它默认要求系统里安装了对应的浏览器内核。很多教程会告诉你装完 MCP 就算完事了但 Windows 上 Playwright 不会自动帮你下载 Chromium需要手动跑一条命令。4.2 解决方案安装 Playwright 浏览器内核在命令行里执行npx playwright install chromium或者你想让它用系统已有的 Chrome 或者 Edge可以执行npx playwright install msedge安装时间取决于网速几 MB 到一百多 MB 不等。装完后再测试Claude Code 就能顺利打开网页了。这里有个差异化建议如果你想做的是抓取页面、跑自动化测试建议装 Chromium如果你是做前端调试想让它操作你正在开发的那个浏览器可以考虑直接让它连接到已有的 Chrome 实例用--channel chrome参数。4.3 深层问题Windows 下的浏览器选用策略还有一个点值得展开。Playwright MCP 在 Windows 下默认使用 Chromium 的无头模式headless也就是没有界面窗口。这样做的好处是节省资源行为也更稳定但对于初次调试的人来说很痛苦——你看不到它在干什么。如果想让 Claude Code 操作时弹出真实的浏览器窗口方便观察可以给 MCP Server 加启动参数claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --headlessfalse这里依然要沿用前缀的写法不然参数传不进去。加了--headlessfalse之后每次 Claude Code 操作浏览器时你都能看到窗口一闪一闪地完成点击、滚动、输入特别直观。还有一个 Windows 特有的问题如果你装的是精简版系统系统里可能同时缺这缺那。Playwright 的浏览器在 Windows 上依赖一些 WebView2 运行时、Media Foundation 组件。缺了之后报错信息会指向某个 dll 文件找不到。这种问题安装 WebView2 Runtime 一般就能解决微软官网直接下就行。顺带提一下如果之前装过老版本的 Playwright可能会残留旧的内核建议在跑npx playwright install chromium之前先执行npx playwright install --list查看当前状态。4.4 小技巧用本机 Edge 代替下载 Chromium如果你不想下载几百 MB 的 Chromium有一个省事的办法Windows 系统自带 Edge 浏览器Playwright 支持直接驱动 Edge。配置方式claude mcp add --scope user playwright -- cmd /c npx playwright/mcplatest --browser msedge --headlessfalse实测下来用系统 Edge 既省了下载时间页面兼容性也更好。唯一的注意点是如果你的 Edge 正在工作被 Playwright 接管后行为可能有点怪最好先关闭正在使用的窗口。这个坑填完之后整条链路终于通了。我让 Claude Code 打开一个网页顺利抓到了页面标题和正文。5. 排错工具箱再遇到问题怎么自己排查三个坑讲完了但说实话每个人的环境差异很大你遇到的报错大概率和我举的例子不完全一样。这里我把排查 MCP 问题的通用思路整理出来了照着顺序检查能少走很多弯路。5.1 最常用的三条诊断命令Claude Code 自带 MCP 诊断命令在终端里跑claude mcp list列出所有已注册的 MCP Server以及它们的连接状态。这个命令能快速告诉你 Server 是否正常启动。如果某个 Server 状态异常接着跑claude mcp get playwright查看单个 Server 的详细配置确认 command 和 args 是否符合预期。如果配置没问题但还是启动不了直接看详细日志claude --debug用调试模式启动 Claude Code它会把每次 MCP 通信的细节打印出来包括启动命令行、退出码、错误输出。这是我这次排查最依赖的工具。5.2 绕过 Claude Code直接测试 MCP Server很多时候MCP 出问题不一定是 Claude Code 的锅而是 Server 本身起不来。这时候别急着在 Claude Code 里反复试先在命令行里手动起一次 Server看它能不能跑。npx playwright/mcplatest如果这条命令在终端里能正常运行、没有任何报错、进程一直挂在那里说明 Server 本身是好的问题出在 Claude Code 和 Server 之间的连接方式。如果这条命令本身就报错那方向就清晰了解决这个报错就好。用这个思路我把问题从“Claude Code 为什么连不上”简化成了“npx 为什么跑不起来”一下就定位到了 PowerShell 执行策略的问题。5.3 Windows 环境特有的几个隐藏坑整理这次经验时我总结了几个 Windows 特有但很少被教程提及的坑杀毒软件和 Windows Defender 的实时防护偶尔会拦截npx从临时目录拉取 package导致下载失败或卡住。如果发现安装超时先把 Defender 的“基于声誉的保护”临时关掉装完再开。不要给 Node.js 和 Claude Code 的安装目录加中文或空格的路径。我见过有人把 npm 全局路径配到C:\Program Files\nodejs\node_cache结果 npx 启动 MCP 时参数解析直接错乱。如果你的系统用户名是中文Claude Code 的配置文件路径里会出现中文目录有些第三方终端可能解析异常。遇到类似情况检查一下%USERPROFILE%路径下能否正常访问。多个版本的 Node 共存时比如通过 nvm-windows 管理Claude Code 启动时可能选错 Node 版本导致 MCP Server 运行在旧版 Node 上。建议用nvm current确认当前版本再启动 Claude Code。6. 跑通之后这套组合能干什么配置跑通之后我实际测了几个场景真实感受就一个字值。6.1 场景一让 Claude Code 抓取页面内容我让它“打开一个页面把页面标题、正文前两段和所有 h2 标题提取出来”它自动打开浏览器等待页面加载完然后提取对应元素再按 markdown 格式输出。整个过程没有任何人工干预。这种能力对做竞品分析、资料收集的人来说非常实用。以前要自己写爬虫或者复制粘贴现在直接用自然语言描述需求它就帮你做了。6.2 场景二自动化测试一个登录流程我拿一个内部系统做测试跟 Claude Code 说“打开登录页输入测试账号密码点击登录告诉我页面是否跳转成功”。它会自动定位输入框、填写内容、点击按钮、判断跳转结果。对测试工程师来说这套组合的潜力在于可以把“写自动化测试脚本”和“执行自动化测试”这两件事合并成一句自然语言。当然真正落地到 CI/CD 还需要不少改造但至少日常验证流程已经足够了。6.3 场景三页面交互和调试前端开发者会喜欢这个场景让 Claude Code 打开某个页面点击某个按钮再告诉你控制台有没有报错。它可以通过 Playwright 监听浏览器的 console 消息和网络请求把信息回传给你。我试过让它“打开本地开发服务器点击导航栏的第三个按钮把 Network 面板里所有请求的 URL 和状态码列出来”它做得挺漂亮省去了我手动打开 DevTools 的功夫。6.4 潜在扩展方向这套组合的扩展空间很大。Playwright 本身支持多浏览器、多标签页、页面截图、PDF 导出、文件下载这些能力 MCP 协议全覆盖了。你可以让 Claude Code 定时截图、批量跑回归用例甚至对接它生成测试报告。我个人的下一个计划是把这套配置接入到日常的自动化巡检流程里让 Claude Code 每天定时打开几个重点页面检查可用性和关键信息有问题就在群里通知。实现思路基本清晰就看实际跑起来有没有坑了。7. 最后聊点心得回头再看这次折腾三个坑分别踩在配置格式、系统环境和浏览器内核上基本覆盖了 Windows 下配置 MCP 的典型雷区。第一个坑是知识盲区第二个坑是系统特性第三个坑是文档不全。每个坑单独拎出来都不难难的是串在一条链路里报错又不会明确告诉你根因在哪。如果你也在 Windows 上配置 Claude Code Playwright MCP我的核心建议只有三条第一Node 版本升到 20 以上第二启动命令用cmd /c npx ...格式绕开 PowerShell第三别忘装浏览器内核。三条全中基本十分钟就能跑通。最后再分享一个小技巧遇到 MCP 配置问题先把 Claude Code 的 debug 日志打开然后强行在命令行列 MCP Server 的启动命令手动跑一遍这两个动作能帮你把问题缩小到“配置错误”还是“环境错误”。我这次如果不是靠这个思路恐怕还要多折腾几个小时。