Playwright MCP 在 Cursor 中的配置流程及使用（自动化测试）

1. 为什么要在 Cursor 里接 Playwright MCP 做自动化测试如果你正在用 Cursor 写前端或做测试大概率遇到过这种场景想验证一个登录流程得先手写 Playwright 脚本跑一遍报错了再改选择器改完再跑。一个简单的「打开页面、输入账号密码、点登录、截图」用例光调试选择器就能耗掉半小时。Playwright MCP 就是来解决这个问题的——它把浏览器操作能力封装成 MCP 工具让 Cursor 里的 AI 直接调用浏览器你只需要用自然语言描述要做什么它就能帮你执行并返回截图和操作日志。Playwright MCP 是微软官方维护的 Model Context Protocol 服务器本质上是把 Playwright 的浏览器自动化能力通过 MCP 协议暴露出来。Cursor 作为支持 MCP 的编辑器接入之后就能在对话里直接指挥浏览器。适合谁用三类人最受益一是做 Web 自动化测试的 QA想快速验证用例而不想每次写脚本二是前端开发想边写页面边让 AI 帮忙点一遍看看有没有明显问题三是刚接触 Playwright 的新手用自然语言驱动浏览器比啃 API 文档上手快得多。我试过在几个项目里用这套组合跑回归用例实测下来最大的感受是「验证成本骤降」。以前改一个表单校验逻辑要手动打开浏览器点半天现在直接在 Cursor 里说一句「打开本地 3000 端口的注册页填错邮箱格式看提示文案对不对」几秒钟就出结果。当然它不能完全替代正式测试脚本但作为开发过程中的快速验证工具效率提升非常明显。这一篇会从零开始把 Node.js 前置、mcp.json 配置、Cursor 里启用 MCP、用一条登录页用例验证、以及常见报错排查全部走一遍。配置片段可以直接复制路径和原文保持一致跑通之后你就能在 Cursor 里用自然语言驱动浏览器了。2. 前置准备Node.js 版本与 Cursor MCP 功能确认在动配置之前有两件事必须先确认否则后面大概率会卡在「MCP 服务器起不来」或者「Cursor 里根本找不到 MCP 选项」上。第一件是 Node.js 版本。Playwright MCP 通过npx playwright/mcplatest启动这个包对 Node.js 有版本要求官方建议 v18 及以上。你可以在终端里跑这两条命令验证node -v npm -v如果node -v输出的是 v18.x、v20.x 或更高就没问题。如果还是 v16 甚至更低建议先去 Node.js 官网下载 LTS 版本覆盖安装。这里有个坑有些人电脑上装了多个 Node 版本终端里node -v显示的是 v20但 Cursor 启动 MCP 时用的可能是另一个路径下的旧版本。稳妥的做法是在 Cursor 的集成终端里也跑一遍node -v确保两边一致。第二件是 Cursor 版本。MCP 功能是 Cursor 较新版本才加入的如果你用的是几个月前的老版本设置里可能压根没有 MCP 这一项。打开 Cursor点左上角菜单检查更新或者去官网下载最新版覆盖安装。更新完之后打开设置快捷键Cmd ,或Ctrl ,在左侧栏找「MCP」或「Features」下的 MCP 相关选项。如果能看到「Add new MCP server」按钮说明版本没问题。还有一点容易被忽略npx首次拉取playwright/mcp包时需要联网下载如果公司网络对 npm registry 有代理限制可能会卡住。你可以先在终端手动跑一次npx playwright/mcplatest --help看看能不能正常拉下来。能出帮助信息说明网络和包都没问题后面 Cursor 里启动也会顺利。这一步相当于提前把依赖预热了避免在 Cursor 里配置完发现一直转圈。另外Playwright 本身需要下载浏览器内核Chromium、Firefox、WebKit。MCP 服务器首次运行时会自动触发下载但如果你网络环境特殊建议提前在终端跑npx playwright install chromium把 Chromium 装好。这样后面验证用例时不会因为浏览器没装而报错。3. 可复制的 mcp.json 配置Mac 与 Windows 差异前置确认完进入配置环节。Cursor 的 MCP 配置有两种方式一种是在设置界面里点「Add new MCP server」手动填另一种是直接编辑mcp.json文件。推荐用后者因为配置片段可以复制粘贴不容易填错字段。先找到配置文件位置。在 Cursor 里打开设置进入 MCP 区域通常会有一个「Edit Config」或「Open mcp.json」的入口点进去会打开一个 JSON 文件。这个文件就是 Cursor 读取 MCP 服务器列表的地方。如果你找不到入口也可以手动在项目根目录或用户目录下创建.cursor/mcp.jsonCursor 会自动识别。Mac 和 Windows 的配置差异主要在command字段。Mac 上直接用npxWindows 上因为npx是.cmd脚本需要套一层cmd /c。下面是两套可直接复制的配置。Mac 配置{ mcpServers: { playwright: { command: npx, args: [ playwright/mcplatest ] } } }Windows 配置{ mcpServers: { playwright: { command: cmd, args: [ /c, npx, playwright/mcplatest ] } } }把对应平台的片段粘贴进mcp.json保存。注意 JSON 格式很严格多一个逗号、少一个引号都会导致解析失败。保存后回到 Cursor 的 MCP 设置界面应该能看到一个名为playwright的服务器条目。如果它旁边显示绿色的点或「Connected」状态说明启动成功。如果是红色或灰色先别急下一节会讲排查。这里补充一个进阶配置项。默认情况下 Playwright MCP 启动的是无头模式headless也就是浏览器在后台跑你看不到界面。如果你希望看到浏览器窗口方便观察操作过程可以在args里加--headlessfalse{ mcpServers: { playwright: { command: npx, args: [ playwright/mcplatest, --headlessfalse ] } } }调试阶段建议开着有头模式能直观看到 AI 点了哪里、填了什么。等用例稳定了再切回无头跑得更快。另外还可以加--browserchromium指定浏览器内核默认就是 Chromium一般不用改。配置保存后Cursor 可能需要重启才能加载新的 MCP 服务器。如果绿点没出现先重启一次 Cursor 再观察。这一步是整个链路里最容易出问题的环节多数失败都集中在 JSON 格式、Node 路径、网络拉包这三类原因上。4. 在 Cursor 中启用 MCP 并用登录页用例验证配置显示绿点之后就可以实际用了。先确认 MCP 工具已经挂载到对话里。在 Cursor 的聊天窗口Chat 或 Composer里输入框附近通常会有一个工具图标或符号点开能看到可用的 MCP 工具列表里面应该有playwright相关的操作比如browser_navigate、browser_click、browser_type、browser_take_screenshot等。看到这些说明工具已经就绪。现在用一条登录页用例来验证整条链路。假设你本地有个登录页跑在http://localhost:3000/login页面上有用户名输入框、密码输入框和登录按钮。在 Cursor 聊天框里输入这样的指令请使用 Playwright MCP 打开 http://localhost:3000/login 在用户名输入框填入 testuser密码框填入 test123456 点击登录按钮然后截图当前页面并告诉我是否跳转成功。发送后Cursor 会调用 Playwright MCP 依次执行启动浏览器、导航到 URL、定位输入框、填入文本、点击按钮、截图。执行过程中你会在聊天里看到每一步的工具调用记录包括传入的参数和返回结果。如果开了有头模式还能看到浏览器窗口自动操作。执行完成后你会收到一张截图和一段文字说明比如「已跳转到 /dashboard页面标题为 Dashboard」。这就说明整条链路跑通了。如果登录失败截图里会显示错误提示你可以根据截图判断是选择器问题还是业务逻辑问题。再进阶一点可以结合需求文档生成测试用例再执行。比如你有一份需求文档A.md在 Cursor 里输入需求文档A.md 分析这个需求的测试点总结后生成一份测试用例文档Cursor 会读取文档内容输出一份结构化的测试用例。然后你再用测试用例.md 根据这个测试用例使用 Playwright MCP 测试功能是否有问题 项目地址http://localhost:3000账号testuser密码test123456它就会按用例逐条驱动浏览器验证。这种方式特别适合回归测试场景——需求文档更新后重新生成用例再跑一遍比手写脚本快得多。需要注意的是指令要尽量清晰。比如「打开百度搜索自动化测试然后截图」这种指令AI 能理解但如果你说「帮我看看那个页面」它不知道是哪个页面。明确 URL、明确操作、明确预期结果执行成功率会高很多。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置和使用过程中有几类报错出现频率最高这里逐个拆解。报错一MCP 服务器显示红色日志里出现local proxy failed或ECONNREFUSED。这通常是npx拉包失败或 Node 路径不对。先在 Cursor 的集成终端里手动跑npx playwright/mcplatest --help看能否正常输出。如果卡住或报网络错误检查 npm registry 配置可以临时切到国内镜像源npm config set registry https://registry.npmmirror.com。如果手动能跑但 Cursor 里不行多半是 Cursor 启动 MCP 时用的 Node 路径和终端不一致。在mcp.json里把command从npx改成 Node 的绝对路径比如/usr/local/bin/npxMac或C:\Program Files\nodejs\npx.cmdWindows能解决大部分路径问题。报错二调用工具时返回401 Unauthorized。这个报错在 Playwright MCP 场景下比较少见因为浏览器操作本身不需要鉴权。但如果你在指令里让 AI 访问了需要登录的接口或者 MCP 服务器配置里误加了需要 token 的远程地址就可能出现。检查mcp.json里是否有多余的env或headers字段Playwright MCP 本地启动不需要这些。如果确实要访问带鉴权的页面让 AI 在浏览器里走正常登录流程而不是在 MCP 层配 token。报错三日志里出现reading choices或Cannot read properties of undefined (reading choices)。这是 Cursor 在解析模型返回时出的错通常和 MCP 本身无关而是模型响应格式异常。遇到这种情况先检查 Cursor 版本是否最新然后尝试换一个模型比如从 GPT 切到 Claude再试。如果换模型后正常说明是特定模型和 Cursor 的兼容问题。另外指令过于复杂也可能导致模型返回格式错乱把大指令拆成几步小指令能降低触发概率。报错四OAuth 相关报错比如OAuth callback failed或invalid_client。这类报错一般出现在你尝试接入需要 OAuth 授权的远程 MCP 服务器时。Playwright MCP 是本地 stdio 模式不涉及 OAuth。如果你在配置里混入了其他远程 MCP 服务器的配置检查那部分的url和auth字段是否正确。对于本地 Playwright MCP确保mcp.json里只有command和args没有url、headers、auth这些字段。排查通用思路先看 Cursor 的 MCP 日志设置里通常有「Show Logs」入口日志会明确告诉你哪一步失败。然后对照上面四类报错定位。多数情况下重启 Cursor、重装 Node、检查 JSON 格式这三招能解决八成问题。6. 接入后的能力延伸与 API 配置建议跑通 Playwright MCP 之后你会发现 Cursor 里的 AI 不仅能操作浏览器还能结合代码上下文做更复杂的事。比如让它「打开登录页故意输错密码然后去代码里找到校验逻辑告诉我哪一行触发了错误提示」。这种「浏览器操作 代码分析」的组合是纯手写脚本很难快速做到的。如果你想把这种能力延伸到更自动化的流程里比如让 CI 或脚本也能调用模型能力可以了解下 TaoToken 的 API 接入方式。它的 API 地址是https://taotoken.net/api支持标准的模型调用接口。在 Cursor 里配置自定义模型时Base URL 填这个地址Key 在控制台的 API Keys 页面生成Model ID 按文档里列出的填。这样你就能在 Cursor 里用上统一的模型入口配合 Playwright MCP 做自动化测试时模型调用和浏览器操作都在一个环境里完成。具体操作路径先到https://taotoken.net/api-keys生成一个 Key然后在 Cursor 的模型设置里选「Custom Model」Base URL 填https://taotoken.net/apiKey 粘贴进去Model ID 按文档填。保存后测试一下对话是否正常。如果返回 401检查 Key 是否复制完整如果返回模型不存在检查 Model ID 拼写。对于长期做编码和 Agent 场景的可以看下 Coding Plan 方案适合需要稳定调用模型跑自动化任务的场景。模型对话入口可以用来快速验证模型是否可用接入文档里有完整的参数说明。这几个入口配合起来基本能覆盖从单次验证到持续集成的需求。最后说个实用技巧Playwright MCP 的截图默认保存在临时目录如果你想留存测试证据可以在指令里明确说「截图保存到项目根目录的 screenshots 文件夹」。AI 会调用相应工具把文件写到指定位置。这样跑完一轮回归截图按时间戳排好出问题直接翻图就行比看日志直观得多。