先交代一下背景。最近我在 Windows 上折腾 Claude Code想让它帮我跑 Web 自动化测试于是盯上了 Playwright MCP。这组合乍看很香Claude Code 负责理解和拆解任务Playwright MCP 负责操作真实浏览器两边一接等于给 AI 装了眼和手。但真配起来才发现Windows 上的坑比我想象的多光是我自己就实打实踩了三个每一个都卡了我不少时间。这篇文章把我从零配置到跑通全流程的记录写下来包括踩坑过程、排查思路和最终解决办法给同样在 Windows 上折腾 Claude Code Playwright MCP 的朋友做个参考。不管你是刚接触 MCP 协议的新手还是已经在用 Claude Code 但被浏览器自动化卡住的老手这篇应该都能帮上忙。1. 先搞清楚 MCP 和 Playwright MCP 是什么1.1 MCP 协议到底解决什么问题MCP全称 Model Context Protocol模型上下文协议。别被这个名字吓到你可以把它理解成 AI 世界的 USB-C 接口。以前你想让 AI 读文件、查数据库、操作浏览器每个都得单独定制对接方案做一个接一个全是脏活累活。MCP 把这件事标准化了AI 这一侧是 host宿主工具那一侧是 server服务端中间用统一的协议通信。host 负责理解用户意图、调用工具、整理结果server 负责真正干活的执行细节。Claude Code 就是一个 MCP host它天然支持接入各种 MCP server。这意味着你不用把每个工具的逻辑都塞进提示词里只要把 server 配置好Claude 就能在对话中自动调用对应工具。比如接了文件系统的 MCP它就能直接读写本地文件接了数据库的 MCP它就能执行 SQL 查询接了 Playwright 的 MCP它就能操作真实浏览器。这种插上就能用的体验确实是 AI 工具链里一个里程碑式的设计。1.2 Playwright MCP 能做什么Playwright MCP 是微软官方出的 MCP server底层就是大名鼎鼎的 Playwright 自动化测试框架。它把浏览器的能力封装成一组 AI 可以调用的工具比如打开页面、点击元素、输入文字、截图、读取页面可访问性快照、执行 JavaScript、监听网络请求等。配好之后你把一个任务甩给 Claude Code比如打开某个网页找到搜索框输入关键词把搜索结果截图发我它会自己规划步骤、调用 Playwright 工具、逐步执行最后把结果给你。这对写端到端测试、调试前端页面、做数据抓取的人来说非常实用相当于把你平时手写 Playwright 脚本的工作变成了用自然语言指挥 AI 去写和执行。当然它也不是万能的。复杂到需要精确控制每个浏览器细节的场景或者需要处理特别刁钻的验证码、反爬逻辑时它依然会有力不从心的时候。但在绝大多数常规页面上它的表现已经相当靠谱。1.3 为什么选官方版而不是第三方封装现在网上 Playwright MCP 的封装版本不少有些还带可视化界面看起来更花哨。但我个人强烈建议直接用微软官方的 playwright/mcp 包。原因有三个第一官方包和 Playwright 框架本身同步更新浏览器兼容性最有保证第二社区里的第三方封装很多也就是套了一层壳核心能力还是依赖官方的东西多一层就多一个出问题的可能第三官方包的文档和 issue 反馈最全真出了问题你能搜到的解决方案也最多。2. 动手前的环境准备Windows 下的安装前检查2.1 Node.js 版本不是越高越好Playwright MCP 和 Claude Code 都依赖 Node.js 环境所以第一步先把 Node.js 装好。这里有个细节很多人会忽略版本不是越新越好。Claude Code 官方要求 Node.js 18 以上但如果你装的是最新的 Node 22 或更高版本个别情况下会和某些 MCP server 的旧依赖产生兼容问题。我常用的是 Node.js 20 LTS 版本稳定兼容性好各种第三方包基本都能跑。安装时注意一点Windows 下安装 Node.js 时一定要确保勾选Add to PATH选项这个选项直接决定了后面你能不能在任何目录下直接使用 npx 命令。如果安装的时候没勾后面所有东西都会卡在第一步这我后面会详细说。装完之后打开终端输入 node -v 和 npm -v能正常输出版本号说明 Node.js 环境就绪了。2.2 Claude Code 的安装与登录Claude Code 本身安装很简单一行命令搞定npm install -g anthropic-ai/claude-code装完后在终端输入 claude 启动第一次会引导你登录。这个过程需要你有对应的 Anthropic 账号权限按提示操作就行。这里我建议你在终端里先把 claude 跑起来随便对话几句确认基础功能正常再去配置 MCP。因为如果连 Claude Code 本身都没跑通后面排查问题的时候会把环境问题和 MCP 配置问题混在一起非常难受。我见过太多人一上来就急着配 MCP结果半天不生效最后发现是 Claude Code 登录状态过期了。基础环境先行这是排查问题的第一原则。2.3 Pip 还是 npx两种接入方式怎么选Playwright MCP 的接入方式有两种一种是通过 npx 直接运行官方包另一种是通过 Python 的 pip 安装 playwright-mcp 包。两种方式都能用但 Windows 下我强烈推荐 npx 方式。原因有几个。npx 方式是微软官方推荐的默认方式文档、示例、issue 里讨论的大多也是这种方式你遇到问题能搜到的解决方案多。另外npx 方式对依赖的管理更干净不需要额外维护一套 Python 环境避免 Python 版本和 pip 依赖冲突这些 Windows 上常见的破事。如果你本来就在用 Python 做 Playwright 开发那选 pip 方式也无可厚非但纯从省心的角度npx 是更稳妥的选择。3. 五步完成 Playwright MCP 配置3.1 用 claude mcp add 命令添加 serverClaude Code 提供了命令行工具来管理 MCP server这是最推荐的配置方式。打开终端输入claude mcp add playwright -- npx playwright/mcplatest这条命令的意思是添加一个名为 playwright 的 MCP server启动方式是通过 npx 运行 playwright/mcp 这个包的最新版本。添加成功后你可以用下面的命令确认claude mcp list看到 playwright 出现在列表里说明配置已经写入了。这条命令默认写入的是用户级配置对所有 Claude Code 项目生效。3.2 手动编辑配置文件的方式有些人喜欢直接改配置文件这也是可以的。Claude Code 的 MCP 配置支持两个作用域项目级的 .mcp.json 文件放在项目根目录只对当前项目生效用户级的配置写在用户目录下的 .claude.json 里对所有项目生效。用 claude mcp add 命令时如果想指定项目级可以加 --scope project 参数claude mcp add playwright --scope project -- npx playwright/mcplatest手动编辑配置文件时结构大概长这样{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }两种方式效果一样看你习惯。我建议新手直接用命令行省得手写 JSON 出格式错误等熟悉了之后再按需改配置文件。3.3 验证配置是否生效配置写完之后怎么确认它真的生效了最直接的办法在 Claude Code 对话界面里输入 /mcp 命令会列出当前会话可用的 MCP server 及其状态。看到 playwright 显示为 connected就说明 MCP server 已经成功连上了。另外一个更底层的验证方式是单独启动 MCP server 测试。因为很多问题出在Claude Code 能配好但 server 本身起不来这时候直接运行npx playwright/mcplatest如果能正常启动并且不报错说明 npx 能找到包、依赖安装没问题、Node 环境正常。这一步能帮你把问题范围缩小到 Claude Code 的配置层面而不是 MCP server 本身。我在实际踩坑过程中发现这一步的排障价值极高强烈建议每次配置完都跑一下。3.4 跑通第一个自动化任务配置验证通过后就可以试试真正的自动化任务了。在 Claude Code 里输入类似这样的指令用 playwright 打开 https://example.com截图然后告诉我页面上有什么内容正常情况下Claude 会调用 Playwright MCP 提供的工具依次完成打开页面、截图、读取快照等操作然后把结果反馈给你。看到这一步跑通说明整个链路已经通了。3.5 配置文件的优先级问题这里有个容易踩的坑Claude Code 的 MCP 配置有优先级关系。项目级的 .mcp.json 会覆盖用户级配置中的同名 server而用户在对话中通过交互方式添加的临时 server 优先级最高。如果你发现配置改了但没生效先检查一下是不是项目里存在优先级更高的配置文件覆盖了你的设置。我在实际使用中就遇到过这种情况明明用 claude mcp add 添加了 playwright也在用户级配置里看到了但进入项目后 /mcp 列表里就是没有。最后发现是项目根目录有个旧的 .mcp.json 把配置覆盖了。把这个文件删除或合并之后一切恢复正常。4. Windows 下我踩的三个大坑4.1 坑一npx 在 Claude Code 里直接失联这是我最先踩到的坑也是 Windows 玩家最容易遇到的问题。配置全部弄好之后进 Claude Code 里一看playwright 的状态是 connected但一让它干活就报错说什么工具调用失败server 端没有响应。后来我开了调试模式仔细看日志才发现 MCP server 根本没有被正常拉起。问题出在哪Windows 下执行命令时系统需要找 npx 的可执行文件。正常来说你在自己打开的终端里敲 npx 是没问题的因为 Node.js 安装时已经把路径加到了你的用户 PATH 环境变量里。但 Claude Code 在 Windows 下拉起 MCP server 时走的是另一个 shell 环境这个环境不一定完整继承了你用户级 PATH 的配置。结果就是Claude Code 内部执行 npx playwright/mcplatest 时根本找不到 npx 这个命令server 自然起不来。解决办法有两个任选其一就可以。第一个办法把 npm 的全局目录明确加到系统级 PATH 里。先执行 npm config get prefix 查看 npm 全局目录比如返回的是 C:\Users\你的用户名\AppData\Roaming\npm那就把这个路径加到系统环境变量 PATH 里。注意是加到系统变量而不是用户变量因为 Claude Code 拉起 MCP 时用的那个 shell 环境下用户变量的继承可能会出问题。第二个办法更直接配置 MCP server 时不用 npx直接指定 npx.cmd 的完整路径。在 Windows 下npm 全局目录里会有 npx 和 npx.cmd 两个文件其中 npx.cmd 才是 Windows 真正会去调用的命令脚本。配置命令改成claude mcp remove playwright claude mcp add playwright -- C:\Users\你的用户名\AppData\Roaming\npm\npx.cmd playwright/mcplatest两个办法我都试过都有效。我个人更推荐第一个办法把 npm 全局目录加入系统 PATH这样以后不管配置哪个 MCP server 都不会再遇到找不到命令的问题。如果你用的是 nvm-windows 或 fnm 这类 Node 版本管理器还要额外注意一下这类工具通常通过符号链接或 shim 来暴露 Node 命令在 Claude Code 内部环境下路径解析更容易出问题。遇到这种情况最快的解决方案是把实际生效的 Node 可执行文件和 npm 全局目录的完整路径都加进系统 PATH。4.2 坑二Playwright 浏览器下载失败搞定 npx 路径问题之后第二个坑马上来了。MCP server 能启动了但 Claude 打开页面时一直报错说浏览器启动失败。我在排查时发现Playwright MCP 默认需要独立的浏览器实例而这个浏览器需要在首次运行时下载。Windows 下这个下载过程非常容易出问题尤其是网络环境不太理想的时候下到一半就断或者直接超时。这里要解释一下 Playwright 的浏览器机制。Playwright 框架本身不内置浏览器它需要单独下载 Chromium、Firefox 或 WebKit 的定制版本。这些浏览器文件默认放在用户目录下的 AppData\Local\ms-playwright 里。Playwright MCP 启动时如果发现没有可用的浏览器就会尝试自动下载但这个自动下载在 Windows 下常常失败而失败的信息又不直观很容易让人误以为是 MCP server 本身的问题。解决办法是手动预下载浏览器。在终端里直接执行npx playwright install chromium这只下载 Chromium 一个浏览器体积相对可控。下载完成后再回到 Claude Code 里重新尝试浏览器就能正常启动了。如果你的网络环境导致官方下载地址连接不稳定还可以通过环境变量切换下载源。Playwright 支持通过 PLAYWRIGHT_DOWNLOAD_HOST 环境变量指定镜像地址比如使用国内镜像$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ npx playwright install chromium这里有个额外提醒下载完浏览器之后一定要确认 Playwright 的版本和浏览器版本是匹配的。如果你之前装过旧版的 Playwright全局缓存里可能有旧版浏览器新版的 Playwright MCP 不认旧版浏览器文件还是会触发下载。遇到下载完还用不了的情况先跑一下 npx playwright install --dry-run 看看当前版本实际需要的浏览器版本再决定是更新缓存还是重新下载。4.3 坑三MCP server 连上却假死第三个坑最隐蔽也最让人抓狂。所有配置都看起来正常/mcp 列表里 playwright 也显示 connected但真让 Claude 操作浏览器时它总是卡住然后过一会儿报超时。看起来像是连接成功了实际上一干活就死。这个问题的根源有两个可能。第一个可能npx 在第一次运行 playwright/mcp 包时需要下载这个包本身。如果之前没有缓存网络又不稳定npx 会在后台慢慢下载这时候 MCP server 虽然显示为 connected但实际上进程还没就绪Claude 一调用工具就卡住直到超时。解决这个问题的笨办法但有效先用 npx playwright/mcplatest 手动跑一次让 npx 完成包下载和缓存之后再配置到 Claude Code 里就不会有首次启动的延迟了。第二个可能Claude 操作浏览器时看不到页面内容。Playwright MCP 默认通过读取页面的可访问性快照来理解页面结构而不是简单截图。如果页面是用特别复杂的 iframe 嵌套或者大量使用了动态渲染组件快照可能会非常庞大或者在读取时卡住。这个问题我的解决思路是在给 Claude 的指令里明确要求它先等待页面加载完成、再获取快照、必要时用截图辅助判断。你可以这样引导打开页面后先等待 3 秒然后用 browser_snapshot 获取页面结构如果结构不完整再用 browser_screenshot 截图查看。我还在调试模式下发现过第三个隐藏原因Windows 防火墙弹窗。Playwright MCP 在启动浏览器时Chromium 进程会尝试绑定本地端口如果系统防火墙弹出了允许/阻止的对话框而对话框没有出现在前台整个操作就会一直阻塞。这种情况在 Windows 服务环境或远程桌面环境下特别容易发生。如果你发现 MCP 一调用浏览器就卡死去任务管理器里检查有没有停滞的 Chromium 进程顺手看一眼 Windows Defender 防火墙的提示有就点允许。5. 常见问题速查表与排查思路我把这段时间遇到的各种问题整理成了一张速查表方便你遇到问题时快速定位现象可能原因排查/解决办法/mcp 列表里 playwright 显示错误或 missingnpx 路径在 Claude Code 环境里不可用手动运行 npx playwright/mcplatest 排除包问题把 npm 全局目录加入系统 PATHserver 显示 connected 但调用工具超时首次运行 npx 需下载包或页面快照过大预执行一次 npx 命令完成缓存引导 Claude 先等待再快照再截图浏览器启动失败Playwright 浏览器未预下载或版本不匹配执行 npx playwright install chromium检查 ms-playwright 目录中的版本是否匹配页面打开后空白或内容不完整页面动态渲染快照读取时机太早在指令中要求等待网络空闲或设置延迟用截图工具辅助判断配置了但完全不生效项目级 .mcp.json 覆盖用户级配置检查项目根目录是否有 .mcp.json调整配置作用域在 PowerShell 里配置成功在 cmd 里失败环境变量或执行策略差异保持终端环境一致检查 PowerShell 执行策略是否阻止脚本运行Windows 下中文路径报错JSON 配置中反斜杠未转义手动编辑配置时路径中的 \ 要写成 \或在命令方式中直接复制完整路径截图全是空白headless 模式下某些页面渲染异常启动 MCP 时加 --headless 参数控制或检查显卡硬件加速相关设置排查问题时我习惯遵循一个顺序先验证 Node 和 npx 可用再验证 MCP 包能单独启动再验证浏览器能单独启动最后才进 Claude Code 里看配置。每一层都先自测通过再往上叠加这样能最大程度避免多个问题混在一起时无从下手。另外Claude Code 提供了调试模式启动时加 --debug 参数可以输出详细日志MCP 相关的调用和报错信息都能在里面看到。日志文件位置在用户目录下的 .claude 目录里。真到山穷水尽的时候翻日志永远比瞎猜有效。6. 跑通之后我的一些使用心得6.1 给 Claude 下指令的技巧配置跑通之后真正决定好不好用的反而是你怎么给 Claude 下指令。我试下来发现指令里信息越具体执行效果越好。比如你说打开网页看看它可能就真的只打开网页然后等你下一步指令但如果你说打开某某页面等待 2 秒获取页面快照找到登录按钮并截图它的执行效率会高很多。另外建议大家把操作有风险的任务拆小。让 Claude 执行表单提交、点击删除按钮这类不可逆操作时我会明确要求它先截图确认再执行下一步。虽然 AI 助手的能力在不断增强但该有的确认环节不能省尤其是在测试环境之外的页面上操作时。6.2 与现有测试框架的协作思路如果你本身就在用 Playwright 做自动化测试可能会纠结有了 Playwright MCP还要不要写传统的 Playwright 脚本我的看法是两者互补。传统脚本适合稳定的、需要反复执行的回归测试场景跑得快、结果稳定、好集成到 CI/CD 里。Playwright MCP 则更适合探索性测试、临时调试、非技术人员也能参与的交互式验证。我现在的工作流是日常回归用传统脚本跑遇到新需求或者要快速验证页面交互逻辑时直接开 Claude Code 用自然语言指挥 Playwright MCP 去做。等验证得差不多了再把验证过程固化成标准脚本。这个组合用下来探索阶段的效率提升非常明显一个页面交互逻辑的初步验证以前要写半天脚本现在几分钟就能出结果。6.3 一些值得留意的边界用了这么久我也总结了一些 Playwright MCP 目前不太擅长的场景给大家提个醒第一涉及复杂文件上传、操作系统级对话框交互的场景它处理得不够好第二强验证码、复杂滑块拖拽这类反自动化机制目前还没有银弹第三页面高度依赖 WebSocket 实时推送数据的场景它的快照机制偶尔会漏掉刚更新的数据。这些场景下该手写代码还是得手写代码。我个人在实际操作中最受用的一个习惯是每周固定清理一次浏览器缓存目录。Playwright 的浏览器文件加上临时 profile 数据会占用不少磁盘空间而且旧版本残留可能引发各种奇怪问题。定期把 AppData\Local\ms-playwright 目录下不用的浏览器版本清掉能让后续使用顺畅很多。这三个坑踩完之后Claude Code 加 Playwright MCP 这套组合已经成了我日常开发调试里离不开的工具。Windows 下配置它确实比 macOS 和 Linux 多一些幺蛾子但只要把 Node 路径、浏览器下载和超时机制这三件事想明白后面基本就是顺畅的。希望这篇文章能帮你少走几个弯路把时间花在真正有意义的事情上。
Windows 下 Claude Code 接入 Playwright MCP：配置实记与踩坑复盘
先交代一下背景。最近我在 Windows 上折腾 Claude Code想让它帮我跑 Web 自动化测试于是盯上了 Playwright MCP。这组合乍看很香Claude Code 负责理解和拆解任务Playwright MCP 负责操作真实浏览器两边一接等于给 AI 装了眼和手。但真配起来才发现Windows 上的坑比我想象的多光是我自己就实打实踩了三个每一个都卡了我不少时间。这篇文章把我从零配置到跑通全流程的记录写下来包括踩坑过程、排查思路和最终解决办法给同样在 Windows 上折腾 Claude Code Playwright MCP 的朋友做个参考。不管你是刚接触 MCP 协议的新手还是已经在用 Claude Code 但被浏览器自动化卡住的老手这篇应该都能帮上忙。1. 先搞清楚 MCP 和 Playwright MCP 是什么1.1 MCP 协议到底解决什么问题MCP全称 Model Context Protocol模型上下文协议。别被这个名字吓到你可以把它理解成 AI 世界的 USB-C 接口。以前你想让 AI 读文件、查数据库、操作浏览器每个都得单独定制对接方案做一个接一个全是脏活累活。MCP 把这件事标准化了AI 这一侧是 host宿主工具那一侧是 server服务端中间用统一的协议通信。host 负责理解用户意图、调用工具、整理结果server 负责真正干活的执行细节。Claude Code 就是一个 MCP host它天然支持接入各种 MCP server。这意味着你不用把每个工具的逻辑都塞进提示词里只要把 server 配置好Claude 就能在对话中自动调用对应工具。比如接了文件系统的 MCP它就能直接读写本地文件接了数据库的 MCP它就能执行 SQL 查询接了 Playwright 的 MCP它就能操作真实浏览器。这种插上就能用的体验确实是 AI 工具链里一个里程碑式的设计。1.2 Playwright MCP 能做什么Playwright MCP 是微软官方出的 MCP server底层就是大名鼎鼎的 Playwright 自动化测试框架。它把浏览器的能力封装成一组 AI 可以调用的工具比如打开页面、点击元素、输入文字、截图、读取页面可访问性快照、执行 JavaScript、监听网络请求等。配好之后你把一个任务甩给 Claude Code比如打开某个网页找到搜索框输入关键词把搜索结果截图发我它会自己规划步骤、调用 Playwright 工具、逐步执行最后把结果给你。这对写端到端测试、调试前端页面、做数据抓取的人来说非常实用相当于把你平时手写 Playwright 脚本的工作变成了用自然语言指挥 AI 去写和执行。当然它也不是万能的。复杂到需要精确控制每个浏览器细节的场景或者需要处理特别刁钻的验证码、反爬逻辑时它依然会有力不从心的时候。但在绝大多数常规页面上它的表现已经相当靠谱。1.3 为什么选官方版而不是第三方封装现在网上 Playwright MCP 的封装版本不少有些还带可视化界面看起来更花哨。但我个人强烈建议直接用微软官方的 playwright/mcp 包。原因有三个第一官方包和 Playwright 框架本身同步更新浏览器兼容性最有保证第二社区里的第三方封装很多也就是套了一层壳核心能力还是依赖官方的东西多一层就多一个出问题的可能第三官方包的文档和 issue 反馈最全真出了问题你能搜到的解决方案也最多。2. 动手前的环境准备Windows 下的安装前检查2.1 Node.js 版本不是越高越好Playwright MCP 和 Claude Code 都依赖 Node.js 环境所以第一步先把 Node.js 装好。这里有个细节很多人会忽略版本不是越新越好。Claude Code 官方要求 Node.js 18 以上但如果你装的是最新的 Node 22 或更高版本个别情况下会和某些 MCP server 的旧依赖产生兼容问题。我常用的是 Node.js 20 LTS 版本稳定兼容性好各种第三方包基本都能跑。安装时注意一点Windows 下安装 Node.js 时一定要确保勾选Add to PATH选项这个选项直接决定了后面你能不能在任何目录下直接使用 npx 命令。如果安装的时候没勾后面所有东西都会卡在第一步这我后面会详细说。装完之后打开终端输入 node -v 和 npm -v能正常输出版本号说明 Node.js 环境就绪了。2.2 Claude Code 的安装与登录Claude Code 本身安装很简单一行命令搞定npm install -g anthropic-ai/claude-code装完后在终端输入 claude 启动第一次会引导你登录。这个过程需要你有对应的 Anthropic 账号权限按提示操作就行。这里我建议你在终端里先把 claude 跑起来随便对话几句确认基础功能正常再去配置 MCP。因为如果连 Claude Code 本身都没跑通后面排查问题的时候会把环境问题和 MCP 配置问题混在一起非常难受。我见过太多人一上来就急着配 MCP结果半天不生效最后发现是 Claude Code 登录状态过期了。基础环境先行这是排查问题的第一原则。2.3 Pip 还是 npx两种接入方式怎么选Playwright MCP 的接入方式有两种一种是通过 npx 直接运行官方包另一种是通过 Python 的 pip 安装 playwright-mcp 包。两种方式都能用但 Windows 下我强烈推荐 npx 方式。原因有几个。npx 方式是微软官方推荐的默认方式文档、示例、issue 里讨论的大多也是这种方式你遇到问题能搜到的解决方案多。另外npx 方式对依赖的管理更干净不需要额外维护一套 Python 环境避免 Python 版本和 pip 依赖冲突这些 Windows 上常见的破事。如果你本来就在用 Python 做 Playwright 开发那选 pip 方式也无可厚非但纯从省心的角度npx 是更稳妥的选择。3. 五步完成 Playwright MCP 配置3.1 用 claude mcp add 命令添加 serverClaude Code 提供了命令行工具来管理 MCP server这是最推荐的配置方式。打开终端输入claude mcp add playwright -- npx playwright/mcplatest这条命令的意思是添加一个名为 playwright 的 MCP server启动方式是通过 npx 运行 playwright/mcp 这个包的最新版本。添加成功后你可以用下面的命令确认claude mcp list看到 playwright 出现在列表里说明配置已经写入了。这条命令默认写入的是用户级配置对所有 Claude Code 项目生效。3.2 手动编辑配置文件的方式有些人喜欢直接改配置文件这也是可以的。Claude Code 的 MCP 配置支持两个作用域项目级的 .mcp.json 文件放在项目根目录只对当前项目生效用户级的配置写在用户目录下的 .claude.json 里对所有项目生效。用 claude mcp add 命令时如果想指定项目级可以加 --scope project 参数claude mcp add playwright --scope project -- npx playwright/mcplatest手动编辑配置文件时结构大概长这样{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }两种方式效果一样看你习惯。我建议新手直接用命令行省得手写 JSON 出格式错误等熟悉了之后再按需改配置文件。3.3 验证配置是否生效配置写完之后怎么确认它真的生效了最直接的办法在 Claude Code 对话界面里输入 /mcp 命令会列出当前会话可用的 MCP server 及其状态。看到 playwright 显示为 connected就说明 MCP server 已经成功连上了。另外一个更底层的验证方式是单独启动 MCP server 测试。因为很多问题出在Claude Code 能配好但 server 本身起不来这时候直接运行npx playwright/mcplatest如果能正常启动并且不报错说明 npx 能找到包、依赖安装没问题、Node 环境正常。这一步能帮你把问题范围缩小到 Claude Code 的配置层面而不是 MCP server 本身。我在实际踩坑过程中发现这一步的排障价值极高强烈建议每次配置完都跑一下。3.4 跑通第一个自动化任务配置验证通过后就可以试试真正的自动化任务了。在 Claude Code 里输入类似这样的指令用 playwright 打开 https://example.com截图然后告诉我页面上有什么内容正常情况下Claude 会调用 Playwright MCP 提供的工具依次完成打开页面、截图、读取快照等操作然后把结果反馈给你。看到这一步跑通说明整个链路已经通了。3.5 配置文件的优先级问题这里有个容易踩的坑Claude Code 的 MCP 配置有优先级关系。项目级的 .mcp.json 会覆盖用户级配置中的同名 server而用户在对话中通过交互方式添加的临时 server 优先级最高。如果你发现配置改了但没生效先检查一下是不是项目里存在优先级更高的配置文件覆盖了你的设置。我在实际使用中就遇到过这种情况明明用 claude mcp add 添加了 playwright也在用户级配置里看到了但进入项目后 /mcp 列表里就是没有。最后发现是项目根目录有个旧的 .mcp.json 把配置覆盖了。把这个文件删除或合并之后一切恢复正常。4. Windows 下我踩的三个大坑4.1 坑一npx 在 Claude Code 里直接失联这是我最先踩到的坑也是 Windows 玩家最容易遇到的问题。配置全部弄好之后进 Claude Code 里一看playwright 的状态是 connected但一让它干活就报错说什么工具调用失败server 端没有响应。后来我开了调试模式仔细看日志才发现 MCP server 根本没有被正常拉起。问题出在哪Windows 下执行命令时系统需要找 npx 的可执行文件。正常来说你在自己打开的终端里敲 npx 是没问题的因为 Node.js 安装时已经把路径加到了你的用户 PATH 环境变量里。但 Claude Code 在 Windows 下拉起 MCP server 时走的是另一个 shell 环境这个环境不一定完整继承了你用户级 PATH 的配置。结果就是Claude Code 内部执行 npx playwright/mcplatest 时根本找不到 npx 这个命令server 自然起不来。解决办法有两个任选其一就可以。第一个办法把 npm 的全局目录明确加到系统级 PATH 里。先执行 npm config get prefix 查看 npm 全局目录比如返回的是 C:\Users\你的用户名\AppData\Roaming\npm那就把这个路径加到系统环境变量 PATH 里。注意是加到系统变量而不是用户变量因为 Claude Code 拉起 MCP 时用的那个 shell 环境下用户变量的继承可能会出问题。第二个办法更直接配置 MCP server 时不用 npx直接指定 npx.cmd 的完整路径。在 Windows 下npm 全局目录里会有 npx 和 npx.cmd 两个文件其中 npx.cmd 才是 Windows 真正会去调用的命令脚本。配置命令改成claude mcp remove playwright claude mcp add playwright -- C:\Users\你的用户名\AppData\Roaming\npm\npx.cmd playwright/mcplatest两个办法我都试过都有效。我个人更推荐第一个办法把 npm 全局目录加入系统 PATH这样以后不管配置哪个 MCP server 都不会再遇到找不到命令的问题。如果你用的是 nvm-windows 或 fnm 这类 Node 版本管理器还要额外注意一下这类工具通常通过符号链接或 shim 来暴露 Node 命令在 Claude Code 内部环境下路径解析更容易出问题。遇到这种情况最快的解决方案是把实际生效的 Node 可执行文件和 npm 全局目录的完整路径都加进系统 PATH。4.2 坑二Playwright 浏览器下载失败搞定 npx 路径问题之后第二个坑马上来了。MCP server 能启动了但 Claude 打开页面时一直报错说浏览器启动失败。我在排查时发现Playwright MCP 默认需要独立的浏览器实例而这个浏览器需要在首次运行时下载。Windows 下这个下载过程非常容易出问题尤其是网络环境不太理想的时候下到一半就断或者直接超时。这里要解释一下 Playwright 的浏览器机制。Playwright 框架本身不内置浏览器它需要单独下载 Chromium、Firefox 或 WebKit 的定制版本。这些浏览器文件默认放在用户目录下的 AppData\Local\ms-playwright 里。Playwright MCP 启动时如果发现没有可用的浏览器就会尝试自动下载但这个自动下载在 Windows 下常常失败而失败的信息又不直观很容易让人误以为是 MCP server 本身的问题。解决办法是手动预下载浏览器。在终端里直接执行npx playwright install chromium这只下载 Chromium 一个浏览器体积相对可控。下载完成后再回到 Claude Code 里重新尝试浏览器就能正常启动了。如果你的网络环境导致官方下载地址连接不稳定还可以通过环境变量切换下载源。Playwright 支持通过 PLAYWRIGHT_DOWNLOAD_HOST 环境变量指定镜像地址比如使用国内镜像$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ npx playwright install chromium这里有个额外提醒下载完浏览器之后一定要确认 Playwright 的版本和浏览器版本是匹配的。如果你之前装过旧版的 Playwright全局缓存里可能有旧版浏览器新版的 Playwright MCP 不认旧版浏览器文件还是会触发下载。遇到下载完还用不了的情况先跑一下 npx playwright install --dry-run 看看当前版本实际需要的浏览器版本再决定是更新缓存还是重新下载。4.3 坑三MCP server 连上却假死第三个坑最隐蔽也最让人抓狂。所有配置都看起来正常/mcp 列表里 playwright 也显示 connected但真让 Claude 操作浏览器时它总是卡住然后过一会儿报超时。看起来像是连接成功了实际上一干活就死。这个问题的根源有两个可能。第一个可能npx 在第一次运行 playwright/mcp 包时需要下载这个包本身。如果之前没有缓存网络又不稳定npx 会在后台慢慢下载这时候 MCP server 虽然显示为 connected但实际上进程还没就绪Claude 一调用工具就卡住直到超时。解决这个问题的笨办法但有效先用 npx playwright/mcplatest 手动跑一次让 npx 完成包下载和缓存之后再配置到 Claude Code 里就不会有首次启动的延迟了。第二个可能Claude 操作浏览器时看不到页面内容。Playwright MCP 默认通过读取页面的可访问性快照来理解页面结构而不是简单截图。如果页面是用特别复杂的 iframe 嵌套或者大量使用了动态渲染组件快照可能会非常庞大或者在读取时卡住。这个问题我的解决思路是在给 Claude 的指令里明确要求它先等待页面加载完成、再获取快照、必要时用截图辅助判断。你可以这样引导打开页面后先等待 3 秒然后用 browser_snapshot 获取页面结构如果结构不完整再用 browser_screenshot 截图查看。我还在调试模式下发现过第三个隐藏原因Windows 防火墙弹窗。Playwright MCP 在启动浏览器时Chromium 进程会尝试绑定本地端口如果系统防火墙弹出了允许/阻止的对话框而对话框没有出现在前台整个操作就会一直阻塞。这种情况在 Windows 服务环境或远程桌面环境下特别容易发生。如果你发现 MCP 一调用浏览器就卡死去任务管理器里检查有没有停滞的 Chromium 进程顺手看一眼 Windows Defender 防火墙的提示有就点允许。5. 常见问题速查表与排查思路我把这段时间遇到的各种问题整理成了一张速查表方便你遇到问题时快速定位现象可能原因排查/解决办法/mcp 列表里 playwright 显示错误或 missingnpx 路径在 Claude Code 环境里不可用手动运行 npx playwright/mcplatest 排除包问题把 npm 全局目录加入系统 PATHserver 显示 connected 但调用工具超时首次运行 npx 需下载包或页面快照过大预执行一次 npx 命令完成缓存引导 Claude 先等待再快照再截图浏览器启动失败Playwright 浏览器未预下载或版本不匹配执行 npx playwright install chromium检查 ms-playwright 目录中的版本是否匹配页面打开后空白或内容不完整页面动态渲染快照读取时机太早在指令中要求等待网络空闲或设置延迟用截图工具辅助判断配置了但完全不生效项目级 .mcp.json 覆盖用户级配置检查项目根目录是否有 .mcp.json调整配置作用域在 PowerShell 里配置成功在 cmd 里失败环境变量或执行策略差异保持终端环境一致检查 PowerShell 执行策略是否阻止脚本运行Windows 下中文路径报错JSON 配置中反斜杠未转义手动编辑配置时路径中的 \ 要写成 \或在命令方式中直接复制完整路径截图全是空白headless 模式下某些页面渲染异常启动 MCP 时加 --headless 参数控制或检查显卡硬件加速相关设置排查问题时我习惯遵循一个顺序先验证 Node 和 npx 可用再验证 MCP 包能单独启动再验证浏览器能单独启动最后才进 Claude Code 里看配置。每一层都先自测通过再往上叠加这样能最大程度避免多个问题混在一起时无从下手。另外Claude Code 提供了调试模式启动时加 --debug 参数可以输出详细日志MCP 相关的调用和报错信息都能在里面看到。日志文件位置在用户目录下的 .claude 目录里。真到山穷水尽的时候翻日志永远比瞎猜有效。6. 跑通之后我的一些使用心得6.1 给 Claude 下指令的技巧配置跑通之后真正决定好不好用的反而是你怎么给 Claude 下指令。我试下来发现指令里信息越具体执行效果越好。比如你说打开网页看看它可能就真的只打开网页然后等你下一步指令但如果你说打开某某页面等待 2 秒获取页面快照找到登录按钮并截图它的执行效率会高很多。另外建议大家把操作有风险的任务拆小。让 Claude 执行表单提交、点击删除按钮这类不可逆操作时我会明确要求它先截图确认再执行下一步。虽然 AI 助手的能力在不断增强但该有的确认环节不能省尤其是在测试环境之外的页面上操作时。6.2 与现有测试框架的协作思路如果你本身就在用 Playwright 做自动化测试可能会纠结有了 Playwright MCP还要不要写传统的 Playwright 脚本我的看法是两者互补。传统脚本适合稳定的、需要反复执行的回归测试场景跑得快、结果稳定、好集成到 CI/CD 里。Playwright MCP 则更适合探索性测试、临时调试、非技术人员也能参与的交互式验证。我现在的工作流是日常回归用传统脚本跑遇到新需求或者要快速验证页面交互逻辑时直接开 Claude Code 用自然语言指挥 Playwright MCP 去做。等验证得差不多了再把验证过程固化成标准脚本。这个组合用下来探索阶段的效率提升非常明显一个页面交互逻辑的初步验证以前要写半天脚本现在几分钟就能出结果。6.3 一些值得留意的边界用了这么久我也总结了一些 Playwright MCP 目前不太擅长的场景给大家提个醒第一涉及复杂文件上传、操作系统级对话框交互的场景它处理得不够好第二强验证码、复杂滑块拖拽这类反自动化机制目前还没有银弹第三页面高度依赖 WebSocket 实时推送数据的场景它的快照机制偶尔会漏掉刚更新的数据。这些场景下该手写代码还是得手写代码。我个人在实际操作中最受用的一个习惯是每周固定清理一次浏览器缓存目录。Playwright 的浏览器文件加上临时 profile 数据会占用不少磁盘空间而且旧版本残留可能引发各种奇怪问题。定期把 AppData\Local\ms-playwright 目录下不用的浏览器版本清掉能让后续使用顺畅很多。这三个坑踩完之后Claude Code 加 Playwright MCP 这套组合已经成了我日常开发调试里离不开的工具。Windows 下配置它确实比 macOS 和 Linux 多一些幺蛾子但只要把 Node 路径、浏览器下载和超时机制这三件事想明白后面基本就是顺畅的。希望这篇文章能帮你少走几个弯路把时间花在真正有意义的事情上。
