如果你跟我一样是在 Windows 上折腾 Claude Code 的开发者那你大概率会在某天遇到 Playwright MCP 这个词。简单说这个组合就是让 Claude Code 获得真实浏览器操作能力打开网页、点击按钮、填写表单、截图保存、抓取页面数据全都能在对话里自然语言完成。听起来很香但真正配起来我在 Windows 下前后踩了三个实打实的坑每个都花了不少时间排查。这篇文章就把完整思路、安装步骤、报错现场和排查过程一起记录下来给后面要配的人当个参考。1. 这套组合是干什么的MCP 把浏览器变成了 Claude 的手和眼1.1 MCP 是什么AI 世界的 USB 接口MCP 全称是 Model Context Protocol模型上下文协议。理解它最好的方式就是拿 USB 接口打比方你的电脑上有 USB 口插上鼠标就能控制光标插上摄像头就能视频通话插上打印机就能出纸各种设备的驱动和通信方式全被这个统一接口消化掉了。MCP 干的就是同一件事只不过把“电脑”换成了 AI 助手把“外设”换成了各种各样的工具和数据源。在 MCP 的体系里Claude Code 属于 MCP Host也就是宿主负责接收你的指令、调度模型被接进来的工具则是 MCP Server也就是服务端比如这里的主角 Playwright MCP。两者通过标准协议对话宿主询问“你能提供哪些工具”服务端返回工具清单宿主在需要时按照参数去调用。这套协议由 Anthropic 提出并开源现在已经有很多工具支持浏览器自动化、数据库查询、设计稿标注、文件系统操作都有对应的 MCP Server。自己动手实现一遍能对比出明显的差距如果不用 MCP你想让 Claude Code 操作浏览器就得让它生成一段 Playwright 脚本再把脚本丢给 Node 去执行结果能不能用全看生成质量。而用 MCP 之后Claude Code 直接调用 Playwright MCP 封装好的工具好比从“让实习生自己写代码调接口”变成了“给实习生一个现成的遥控器”稳定性和可控性完全不在一个级别。1.2 为什么偏偏是 Playwright MCPPlaywright 是微软开源的浏览器自动化框架支持 Chromium、Firefox、WebKit 三种内核特点是稳定性高、API 统一、内置等待和重试机制。它本身是给测试人员写自动化脚本用的但官方后来做了一个playwright/mcp包把这套能力封装成 MCP 服务相当于把整个浏览器自动化框架直接开放给 AI 调用。选择它的理由对我个人来说很直接。第一它是微软官方团队维护的项目不是第三方个人作品长期使用更放心。第二它提供的工具很完整页面跳转、点击、输入、截图、滚动、提取页面快照全都有。第三它能实时感知页面状态。比如你让它“把搜索框里的内容清空再输入新关键词并搜索”它可以通过可访问性快照看到当前页面的表单结构而不是像写死的脚本那样容易失效。市面上也有其他浏览器类 MCP比如 Puppeteer MCP、Browser MCP 等。我最终选 Playwright 还有一层原因配置方式天然跨平台。在 Windows 上这一套命令跑通之后换到其他系统也基本是同样流程学习成本不会浪费。1.3 配置成功之后能做什么我配好之后最常用的场景有四类。第一让 Claude 打开一个本地或线上页面截图给我看省得自己一次次刷新调试。第二自动填表比如登录页的账号密码输入、表单提交直接对话描述就能完成。第三页面数据抓取让 AI 打开列表页翻页采集信息再整理成结构化数据返回。第四写自动化测试时先让 Claude 走一遍关键路径把实际点击过程记录下来作为后续测试脚本的参考。这篇博文不打算做太多理论铺垫重点放在 Windows 上从零配置的实操路径以及我实打实踩过的三个坑。如果你现在还没有装 Node.js或者对 MCP 还一知半解跟着下面的步骤走一遍就能跑起来整套流程大概二十分钟。2. Windows 下安装与注册一步步搭好环境2.1 第一步装一个干净的 Node.jsClaude Code 和playwright/mcp都是 Node.js 应用所以第一步是装 Node.js。我的建议是直接从官网下载 LTS 长期支持版的安装包别追新稳定性优先。安装的时候有一个关键勾选项Add to PATH。很多人后面在命令行里执行claude提示找不到命令十有八九是这一步没勾上或者装完之后没有重开一个终端窗口。装好后打开新的 PowerShell 窗口验证三件事node -v npm -v能正常显示版本号就说明 Node 环境没问题。我用的是 Node.js 20 LTS目前 Claude Code 和 Playwright 对 Node 版本都有要求如果你的版本低于 18建议直接升级。在旧版本上纠结不值得后面各种依赖装不上会更痛苦。如果你之前装过旧版 NodeWindows 下升级最省心的方案是直接覆盖安装新的 LTS 安装包会自动处理大部分路径。卸载重装也可以但记得把安装目录里的 node_modules 残留清干净避免一些奇怪的缓存问题。装完之后顺便执行一句npm config get registry看一下镜像源配置如果默认源下载慢可以配置成国内镜像这一步对后续安装速度和成功率影响很大。2.2 第二步安装 Claude Code 并确认版本Node 就绪后打开 PowerShell执行全局安装npm install -g anthropic-ai/claude-code这一步会下载 Claude Code 的命令行工具。装完验证claude --version如果能打印出版本号说明安装成功。如果提示“不是内部或外部命令”或者是“无法识别”基本就是 PATH 问题回到上一小节处理。还有一类非常典型的 Windows 问题PowerShell 禁止运行脚本导致claude命令不能正常从终端启动。这个坑我在第三章展开讲这里先不急着踩。首次运行claude它会引导你登录 Anthropic 账号并完成授权。这一步在命令行里走一遍浏览器授权流程即可登录成功之后认证信息会保存在本地后续使用不需要重复登录。如果你遇到授权流程无法完成可以先检查一下系统层面有没有对 localhost 回环请求做拦截这类网络配置问题偶尔会碰到通常调整一下就能过去。2.3 第三步用 claude mcp add 把 Playwright 接进来Claude Code 内置了一个 MCP 管理命令叫claude mcp add。把 Playwright MCP 注册进来的命令是这样claude mcp add playwright -s user -- npx playwright/mcplatest简单解释一下这条命令playwright是这个连接的名称-s user表示作用域是当前用户配置对所有项目生效。如果你只想让某个项目使用可以去掉-s user此时配置会写到当前项目的.mcp.json里。--后面的部分是要实际执行的命令这里通过 npx 拉取并运行playwright/mcp的最新版本。执行完之后检查一下注册结果claude mcp list这个命令列出当前所有已配置的 MCP 服务。看到 playwright 那一行状态是 connected说明链路已经通了。如果显示 failed 或者没有显示大概率是环境变量、执行策略或者路径解析的问题后面排查章节会覆盖最常见的场景。如果你更喜欢手动编辑配置也可以直接操作文件。用户级配置在%USERPROFILE%\.claude.json项目级配置在项目根目录的.mcp.json。手动写的话内容大致是{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest], env: { PLAYWRIGHT_HEADLESS: true } } } }用命令行注册的好处是它能自动处理大量的转义细节手写 JSON 在 Windows 路径上很容易踩坑这正好是我遇到的第二个坑下面展开说。3. 三个坑的完整现场从报错到解决的排查实录这一章是全文的核心我把三个坑按时间顺序完整重现。每个坑都包括症状表现、排查思路、最终解决和原因解释照着走能省下不少时间。3.1 坑一PowerShell 执行策略拦路npx 无法运行第一个坑发生在我执行完claude mcp add之后的验证阶段。命令行本身没有报错但等我真的在 Claude Code 会话里让它操作浏览器时MCP 服务根本起不来。我切到单独的 PowerShell 窗口手动执行 npx 相关命令直接弹出一段红字无法加载文件 C:\Program Files\nodejs\npx.ps1因为在此系统上禁止运行脚本。 有关详细信息请参阅 about_Execution_Policies。看到这个报错我的第一反应是命令拼写有问题但反复检查发现并不是。真正的原因是Windows PowerShell 默认的执行策略是 Restricted也就是禁止运行任何 .ps1 脚本。npx 在 PowerShell 里并不是直接执行 npx.exe而是通过一个 npx.ps1 包装脚本调用的策略一拦整个命令就直接废掉。Claude Code 在内部启动 MCP 服务时如果走的是 PowerShell 通道自然也会失败。解决办法是在当前用户维度放宽执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser命令执行后会有一个确认提示输入 Y 回车即可。这里我特意选择的是 RemoteSigned 而不是 Unrestricted。RemoteSigned 的含义是本地创建的脚本可以运行从网上下载的脚本必须有数字签名才允许运行。既能满足 npx 这类本地脚本的运行需求又不会把系统安全策略完全放开折腾开发环境也要守住底线。注意改完 PowerShell 执行策略之后一定要重新打开终端窗口再测试。执行策略是在终端启动时读取的已经打开的旧窗口不会自动刷新。改完策略后重新开一个 PowerShell 窗口再跑npx -v就不会报错了。顺带提一句Windows 上有的开发者默认用 CMD 而不是 PowerShellCMD 下没有 .ps1 拦截问题所以很多人根本没踩过这个坑。但只要你的终端是 PowerShell这个坑就迟早会遇到。3.2 坑二Windows 路径反斜杠在 JSON 里被“吃掉”第二个坑是在我尝试不用 npx、而是直接指定 Playwright MCP 脚本绝对路径的时候踩到的。当时我想与其让 npx 每次去远程解析不如直接把cli.js的完整路径写进配置也许启动速度还能快一点。结果这个想法在 Windows 上差点把我绕晕。我先确认了playwright/mcp的实际安装位置一般在全局 npm 包目录下然后直接执行claude mcp add playwright -s user -- C:\Users\myname\AppData\Roaming\npm\node_modules\playwright\mcp\cli.js命令执行成功但claude mcp list显示 playwright 一直处于 failed 状态。我去翻生成的配置文件发现路径里的反斜杠全被吞了比如C:\Users\myname在 JSON 里变成了C:Usersmyname。这就是典型的 Windows 反斜杠和 JSON 转义冲突JSON 里的\是转义符\U、\A这样的字符会被解析成特殊含义或者干脆被丢弃。排查时我一度以为是claude mcp add命令在解析参数时出了问题直到直接打开%USERPROFILE%\.claude.json看内容才发现是 JSON 层的转义问题。解决方式有三种按省心程度排序最简单回到npx playwright/mcplatest的方式不写任何绝对路径把路径解析问题全部交给 npx。手动配置编辑 JSON 时把所有反斜杠写成双反斜杠\\或者统一改成正斜杠/Node.js 在 Windows 下原生支持正斜杠。用相对路径把 cli.js 路径改成相对于当前工作目录的写法减少转义面。最后我选择的是第一种用 npx 方式一劳永逸。这里也想多说一句Windows 下配置任何工具的路径只要最终落到 JSON 里优先用正斜杠。这是我从这个坑里学到的通用习惯正斜杠在 Windows API 和 Node.js 里都能正确识别能避开无数的转义问题。3.3 坑三Playwright 浏览器内核没装MCP 空转第三个坑是最隐蔽的。当我把前两个问题解决、claude mcp list显示 connected、MCP 服务也正常启动之后在 Claude Code 里测试让它打开网页它竟然跟我说执行失败。我把日志翻出来看核心报错是browserType.launch: Executable doesnt exist at C:\Users\myname\AppData\Local\ms-playwright\chromium-1169\chrome-win\chrome.exe这行报错的含义是Playwright 框架在系统缓存目录下找不到对应版本的浏览器内核。很多第一次用的人会困惑明明playwright/mcp装好了为什么还缺浏览器因为 Playwright 框架的设计把“浏览器管理”和“自动化 API”分开了npm 包里只有 API 代码浏览器内核是单独的组件需要额外下载安装。打个比方你买了游戏客户端但游戏引擎需要单独下载两个缺一个都跑不起来。解决方式就是显式安装浏览器内核。在 PowerShell 里执行npx playwright install chromium这条命令会把 Chromium 内核下载到系统缓存目录也就是上面报错里那个ms-playwright目录。我的建议是只装 chromium除非你有 Firefox 或 WebKit 的明确测试需求否则没必要下载另外两个一个就好几个 GB纯属浪费磁盘空间。如果你网络不好下载会非常慢甚至直接超时可以临时切换下载源。Windows 下先设置环境变量再执行安装$env:PLAYWRIGHT_DOWNLOAD_HOST https://cdn.npmmirror.com/binaries/playwright npx playwright install chromium这是国内镜像加速的常规做法只是把二进制下载地址指到提速节点不涉及其他任何额外操作。装好之后再次在 Claude Code 里测试浏览器就能正常启动。如果你不想每次操作都弹出浏览器窗口可以在注册 MCP 时加上 headless 参数让浏览器在后台无头运行资源占用小很多也适合自动化批处理场景。4. 验证连通性与真实使用效果4.1 会话内测试让 Claude 打开网页并截图环境配好之后我建议先做一轮最简单但最有效的验证在 Claude Code 会话里直接输入类似这样的指令请打开 https://example.com 等待页面加载完成后截图并把截图保存到当前目录的 test.png如果一切正常Claude 会调用 Playwright MCP 的browser_navigate打开页面然后调用browser_snapshot获取页面可访问性快照掌握页面结构再执行截图操作。你还会注意到Claude 的操作过程和 Playwright 测试脚本的流程几乎一致先定位元素再执行动作最后确认结果。这就是 MCP 的价值——它把底层细节屏蔽掉了你只需要用自然语言描述目标剩下的交给模型去拆解工具调用。我第一次测试时特意选了 example.com 这种静态页面因为它没有复杂的异步加载和登录拦截能最快确认链路是否通畅。等确认没问题之后再逐步上真实业务页面。如果你测试的是本地开发环境页面比如 localhost:8080Claude 可能会提示需要授权读取本地内容确认放行就行这个授权机制是 Claude Code 自己的安全设计建议保留而不是关掉。4.2 常用工具和参数以及不同场景怎么调playwright/mcp提供的工具大致可以分为几类导航类有browser_navigate、browser_go_back、browser_reload交互类有browser_click、browser_fill、browser_press_key、browser_select_option提取类有browser_snapshot、browser_screenshot、browser_get_text标签页管理类有browser_new_page、browser_close_page。你在 Claude Code 里输入/mcp就能看到已加载服务的工具列表也可以直接在对话里问它支持哪些操作。实际使用中我对两个参数特别满意。第一个是--headless加了之后浏览器不会弹出窗口做后台任务非常合适。第二个是--device可以模拟手机设备Claude 会按照移动端视口操作浏览器适合跑移动端页面适配和真机效果预演。注册命令可以写成claude mcp add playwright -s user -- npx playwright/mcplatest --headless --deviceiPhone 13需要注意这些参数配置好之后要重启 Claude Code 会话才会生效。改完配置发现行为没变化先检查是不是没有重启这是我反复吃过亏的地方。另外--device参数的值要和 Playwright 官方支持的设备名完全一致否则会启动失败具体列表可以在 Playwright 文档里查到。4.3 日常使用中的几个关键建议用了一两周之后我有几个比较实在的建议。第一把容易产生不可逆操作的测试场景放在独立环境里不要拿生产数据去试。AI 操作浏览器的速度很快万一误点了删除、提交、支付这类按钮后果不可控这一点怎么强调都不过分。第二给每个任务明确规定范围比如在指令里写明“只查看不要点击任何按钮”模型多数时候能尊重指令但边界写清楚能减少大量意外。第三遇到复杂页面时先让 Claude 截图而不是直接操作。它虽然会自动获取页面快照但如果页面里嵌套了大量 iframe 或者有动态渲染内容截图往往比抽象的 DOM 描述更直观也能更快定位问题。第四如果项目里已经沉淀了 Playwright 测试用例建议保留。MCP 的价值在于“随时让 AI 帮我操作浏览器”的灵活需求而测试脚本是回归保障两者不是替代关系是互补关系。5. 常见问题速查表与最后的叮嘱5.1 速查表症状、原因、解决我把这次配置过程中所有值得记录的问题整理成一张表方便你直接对照排查症状原因解决办法执行 npx 或 claude 脚本时报“禁止运行脚本”PowerShell 执行策略是 Restricted执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUserclaude mcp list显示 failed配置里路径变形JSON 反斜杠转义问题用 npx 方式或路径写正斜杠/双反斜杠MCP 显示 connected但调用时找不到浏览器内核Playwright 浏览器未安装执行npx playwright install chromium浏览器内核下载慢或总是失败网络到官方下载源不稳定临时设置 PLAYWRIGHT_DOWNLOAD_HOST 为国内镜像地址claude命令提示找不到Node.js 未加入 PATH重装 Node 勾选 Add to PATH或手动配置环境变量改完 MCP 配置不生效Claude Code 会话未刷新重启 Claude Code 会话或重连 MCP浏览器频繁弹窗占用系统资源非无头模式注册 MCP 时加--headless参数页面存在大量 iframe 无法正常操作默认快照不包含深层 iframe 内容让 Claude 先截图分析页面结构再针对性处理5.2 这套配置给我带来的实际变化这套配置跑通之后我最大的感受是“AI 编程助手终于有了眼睛”。以前让它改前端样式它是闭着眼睛改的只能靠猜现在它可以先打开页面看一眼当前效果再去做对应的调整生成的代码明显更贴合实际。我会建议身边做前端、测试、自动化相关的开发者都试一下尤其是 Windows 环境下的朋友踩坑记录都在这里了照着走能省不少时间。最后分享一个小技巧如果你经常需要登录态的页面操作可以让 Claude 打开目标网站完成登录后保持浏览器会话数据不清空。playwright/mcp支持通过--user-data-dir参数指定一个独立的浏览器配置文件目录把登录状态持久化下次启动就不用重复扫码或输入密码。这是我实际用下来觉得最提升效率的进阶配置配合 headless 模式做定时巡检、页面监控之类的工作顺手程度会超出预期。