为 Claude Code 添加 Playwright MCP

核心摘要

最稳妥的最短路径是：确认 Node.js 可用，通过明确的 stdio 命令添加 Playwright MCP，检查服务器显示为已连接，再完成一次只读冒烟测试。基本流程跑通前，不要加入持久化浏览器配置、无限制文件访问、宽泛的来源范围或生产环境凭据。

为 Claude Code 添加 Playwright MCP

先检查运行条件

官方 Playwright MCP 仓库当前要求 Node.js 18 或更高版本。请在准备添加服务器的同一个终端中依次确认 node --version、npx --version 和 claude --version 都能正常运行。这样可以提前发现 Windows 或 macOS 上常见的 PATH 问题：Node.js 虽已安装，但当前终端或 Claude Code 进程尚未读取新的环境变量。遇到旧命令格式或状态显示异常时，也应先更新 Claude Code。

注册本地 stdio 服务器

在需要使用该服务器的项目目录中运行 claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest。其中 playwright 是 Claude Code 显示的服务器名称，npx 负责启动 Microsoft 的软件包。按照当前 Claude Code 语法，双横线后的内容全部传给服务器命令，因此这个分隔符很重要。Playwright 仓库中的简写命令在兼容版本中可能仍然可用，但明确写出传输方式和分隔符，更容易判断每个参数由谁处理。

有意识地选择 local、project 或 user

local 是默认作用域，它会在用户配置中保存一份与当前项目关联的私有设置，不会向代码仓库新增共享文件，因此最适合作为首次配置。project 会在项目根目录生成团队可共享的 .mcp.json；Claude Code 会要求用户批准项目级服务器，所以提交前应审查命令和软件包来源。user 会让多个项目都能看到该服务器，适合个人长期使用的开发工具，但也扩大了浏览器工具的可用范围。

• --scope local：仅供一个开发者在当前项目使用，适合第一次安装。
• --scope project：团队已经审查服务器定义，并希望把 .mcp.json 纳入版本管理时使用。
• --scope user：只有同一用户的所有项目都需要这项浏览器能力时才使用。

分别验证“已写入配置”和“连接成功”

命令返回“Added”只说明配置已经写入，并不代表服务器已成功启动。接着运行 claude mcp list，确认状态为 Connected；再用 claude mcp get playwright 检查保存的命令与作用域。随后在目标项目中打开 Claude Code，通过 /mcp 查看会话内状态。project 作用域的服务器在工作区获得信任并完成批准前，可能显示为等待审批；连接失败则说明进程启动或 MCP 握手没有完成，即使注册本身已经成功。

采用“检查—执行—验证”工作流程

用只读测试确认工具可用

不要一上来就登录或提交表单。先让 Claude Code 打开一个公开网址，报告最终网址和页面标题，识别一个可见标题，并列出一个具名链接但不点击；随后只允许一次页面跳转，再报告新网址和标题。这个小测试可以同时验证浏览器启动、导航、无障碍快照、工具返回值和状态刷新，而且几乎不会产生实际影响。

把请求写成任务约定

有效的浏览器请求应包含起始网址、目标结果、允许访问的域名、可执行动作、禁止事项、人工检查点和成功证据。应描述最终要实现什么，而不是指定未经验证的点击坐标。例如：检查测试环境的设置页，找到 Webhook 表单，填写给定内容，报告所有字段，并在保存前停止。即使页面布局发生变化，这个任务目标仍然清晰。

• 第一次操作前，先检查当前网址和页面的可访问结构。
• 通过角色、可见标签、名称或稳定的测试 ID 定位控件，不依赖坐标。
• 一次只执行一个边界明确的动作，并等待预期状态变化。
• 导航、刷新、弹窗、iframe 或动态内容变化后，重新检查页面。
• 返回最终网址，以及能够直接证明任务结果的页面证据。

只在任务需要时增加配置

Playwright MCP 支持浏览器类型、无头模式、隔离会话、持久化用户数据、存储状态、输出目录、超时、设备模拟和附加能力等选项。首次运行应保留默认浏览器与会话行为；需要一次性环境时加入 --isolated，必须验证特定浏览器引擎时使用 --browser，截图和跟踪文件需要固定位置时再设置 --output-dir。--user-data-dir 和已保存的登录状态可能保留 Cookie 与账号访问权限，必须作为敏感配置管理。

把稳定检查沉淀为正式测试

MCP 适合探索、调试和执行路径经常变化的任务。当同一项断言需要在每次构建中重复运行时，应把它改写为标准 Playwright 测试，明确测试夹具、定位方式、断言、重试和 CI 报告。MCP 可以帮助摸清流程，但纳入代码库的测试才是可重复的交付物。如果还在比较不同浏览器 MCP 方案，可阅读相关的 浏览器 MCP 选择指南；该页面讨论选型，不重复这里的安装步骤。

安全与调试实践

按故障层排查，不要反复重装

• 找不到命令：确认 Node.js、npx 和 Claude Code 在同一终端中可用；PATH 修改后重新打开终端。
• 连接失败：用 claude mcp get playwright 检查保存的配置，单独运行其中的 npx 命令，并从第一条进程错误开始排查。
• 等待审批：以交互方式打开项目，确认信任工作区，并审查 project 作用域的服务器定义。
• 浏览器无法启动：检查浏览器安装、可执行权限、沙箱限制、代理设置和配置文件冲突。
• 元素突然消失：导航或动态更新后重新获取页面快照，不要继续使用旧引用。
• 疑似重复提交：重试前先检查确认提示、网址变化和重复记录。

让浏览器权限小于等于任务范围

尽量使用测试账号或专用浏览器配置文件。密码、API Key、恢复码和原始 Cookie 不应出现在提示词或长期日志中。Playwright MCP 提供来源过滤选项，但官方同时说明，允许来源并不构成安全边界，也不能约束重定向。因此，过滤规则不能替代账号隔离、最小权限和人工审批。除非任务确实需要读取本地文件，否则不要开放无限制文件访问；每次上传都要核对准确路径和目标站点。

在高影响操作前即时暂停

在获准域名内进行只读检查通常可以直接继续；起草文字或填写尚未提交的表单，应在复核点暂停；发送消息、接受法律条款、购买、发布、修改权限、上传私密数据或删除记录，则必须在最后一步执行前取得明确授权。授权提示应写清目标对象和具体内容，让审批者准确知道将发生什么变化。

QVeris 如何与 Playwright MCP 协同

让每一层承担最适合的工作

• Claude Code 必须读取渲染状态、操作界面专属控件或探索变化中的网页流程时，使用 Playwright MCP。
• 如果类型明确的输入和可预测输出能够替代浏览器交互，可通过 QVeris 发现并调用结构化 API 或工具。
• 也可以让 API 先准备或校验结构化数据，再由 Playwright MCP 完成只有界面才能执行的步骤。
• 需要稳定重复运行的浏览器断言，应写入正式 Playwright 测试，而不是每次重新组织智能体提示词。

QVeris 不负责安装本地 MCP 服务器，也不会管理 Node.js 进程或代替用户批准 Claude Code 权限。只有当更完整的智能体流程需要在浏览器自动化之外调用经过核验的结构化能力时，QVeris 才开始发挥作用。如果任务只是“在本地安装 Playwright MCP”，直接按照上面的 Microsoft 与 Anthropic 官方说明操作即可。

常见问题