最近在 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/mcp@latest直接报语法错误，根本起不来。后来查了官方文档，发现要求 Node 18 以上，Recommended 区域甚至建议 Node 20+。我把 Node 升级到 22 LTS 之后，世界瞬间清净了。

这里有个小提示：Windows 下升级 Node 不要直接覆盖安装，容易留残留文件。建议先把旧版本彻底卸载，再装新版。装完在 PowerShell 里执行node -v确认版本号没问题再继续。

1.2 安装 Claude Code：npm 方式最省心

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 是 Host，@playwright/mcp是 Server，浏览器内核是最终干活的人。Claude Code 启动时，会读取 MCP 配置文件，里面写着每个 Server 应该如何启动（用什么命令、带什么参数）。然后 Claude Code 通过标准输入输出（stdio）或者 HTTP 与 Server 通信，把自然语言请求转换成工具调用指令，发给 Server，Server 再驱动浏览器执行。

用生活场景类比：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/mcp@latest

或者手动在配置文件里写入：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }

注意args是一个字符串数组。我第一次偷懒，把它写成了这样：

{ "args": "@playwright/mcp@latest" }

这就是一个字符串了，不是数组。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/mcp@latest

这条命令把 playwright 注册到当前用户的 MCP 配置里，启动方式是npx @playwright/mcp@latest。如果后面要加参数，比如指定浏览器，就接着写：

claude mcp add --scope user playwright -- npx @playwright/mcp@latest --browser chromium

--前面的部分是 Claude Code 的参数，后面的是要交给 MCP Server 的启动参数。

配置完之后，用claude mcp list确认一下子项状态。正常会显示类似：

✔ playwright - npx @playwright/mcp@latest (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/mcp@latest

结果报了一个很经典的错：

无法加载文件 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/mcp@latest验证。

第二种方案：在 Claude Code 的 MCP 配置里，把启动命令从npx改成cmd /c npx。这样 Clauede Code 会强制用 CMD 去启动 npx，走的是npx.cmd，不涉及 PowerShell 脚本。配置命令是：

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

第三种方案：干脆不用 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/mcp@latest @--browser chromium

注意到没，参数前面补了一个@符号。这是因为 Claude Code 的--后面的内容会原样传给 Server，但如果你通过cmd /c启动，参数解析规则会变，需要把参数用@前缀包一层，才能正确传到 npx。这个细节非常坑，我也是试了三次才试出来。

3.4 顺手验证 Node 版本

第三个隐蔽问题：如果 Node 版本太老，MCP Server 本身可能起不来。执行策略搞定之后，我单独跑npx @playwright/mcp@latest时，又遇到了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 doesn't 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/mcp@latest @--headless=false

这里依然要沿用@前缀的写法，不然参数传不进去。加了--headless=false之后，每次 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/mcp@latest @--browser msedge @--headless=false

实测下来，用系统 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/mcp@latest

如果这条命令在终端里能正常运行、没有任何报错、进程一直挂在那里，说明 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 的启动命令手动跑一遍，这两个动作能帮你把问题缩小到“配置错误”还是“环境错误”。我这次如果不是靠这个思路，恐怕还要多折腾几个小时。