Claude Code Playwright MCP 接入教程

Name: Claude Code Playwright MCP 接入教程
Author: 佚名

在远程 Mac mini 上安装配置并验证浏览器自动化

发布建议日期 2026-10-24 适用于前端测试与远程浏览器自动化

Playwright MCP 可以让 Claude Code 读取网页的可访问性快照，并按元素引用执行导航、点击、输入和表单操作。本文演示如何在一台长期在线的 Mac mini 上完成项目级接入，验证第一个浏览器任务，再根据调试、无人值守和登录保持需求选择合适的浏览器模式。

Playwright MCP 适合解决什么问题

普通代码助手可以编写测试，却看不到当前网页状态。Playwright MCP 把浏览器能力作为 MCP 工具提供给 Claude Code，并通过结构化的可访问性快照返回元素引用。Claude Code 可以据此定位按钮、输入框和列表，不必依赖坐标猜测。

这套方式适合探索页面流程、复现前端问题、生成端到端测试草稿和执行重复验收。对大规模高吞吐测试，官方也建议评估 Playwright CLI，因为 CLI 输出更紧凑；本文聚焦需要持续浏览器上下文和交互推理的 MCP 场景。

在远程 Mac 上安装 Node.js 20 或更高版本，并把 Claude Code 更新到当前版本。确认 node、npm、npx 和 claude 都能在终端中直接运行。首次启动 Playwright MCP 时会下载浏览器组件，因此需要稳定网络和足够磁盘空间。

准备一个不含真实客户数据的测试站点或测试账号。浏览器自动化可能点击按钮、填写表单或提交内容，首次接入不要直接操作生产环境，也不要把账号密码写进仓库或提示词。

Claude Code 的 MCP 配置可分为 local、project 和 user。个人试验优先使用 local；希望团队共享同一套无密钥配置时使用 project；多个项目都需要相同浏览器工具时可用 user。

本文采用 project 范围，配置会写入项目根目录的 .mcp.json。该文件可以提交，但其中不要放 Cookie、令牌或账号密码。团队成员首次使用项目级 MCP 时，Claude Code 会要求确认是否信任该服务器。

进入项目根目录后执行添加命令。双横线把 Claude Code 自身参数与 MCP 服务器命令分开；npx 的 -y 参数用于避免首次运行时等待安装确认。

也可以手动创建 .mcp.json。两种方式选一种即可，不要重复添加同名服务器。保存后用 claude mcp list 和 claude mcp get playwright 检查实际配置。

cd /path/to/your-project
claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest
claude mcp list
claude mcp get playwright

也可以手动创建以下项目级配置：

{
  "mcp******s": {
    "playwright": {
      "com**nd": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

启动 Claude Code，输入 /mcp，确认 playwright 显示为已连接。若是项目级配置，按界面提示批准该服务器。然后用公开的 TodoMVC 演示页执行第一个任务，避免一开始就接触登录页或真实业务。

成功时，Claude Code 会先导航到页面，读取可访问性快照，再把输入框的元素引用传给输入工具。完成后应看到新增待办，并能再次读取更新后的页面状态。

打开 https://demo.playwright.dev/todomvc
新增一条待办：检查 Playwright MCP 接入
确认页面显示 1 item left
不要访问其他站点

验收项	通过标准
运行环境	node 与 npx 可用且 Node.js 版本不低于 20
MCP 连接	claude mcp list 显示 playwright
会话确认	/mcp 中服务器状态正常
页面读取	能返回 TodoMVC 的输入框与列表快照
页面操作	能新增测试待办并读取更新状态
安全边界	使用测试账号且未提交 Cookie 或存储状态

Playwright MCP 默认使用有界面模式，适合首次调试，因为你可以通过 UU 远程桌面观察浏览器。长期定时验收可改成 headless，减少桌面依赖。

默认持久化配置会保留登录状态和 Cookie，并按项目区分浏览器资料。需要每次从干净状态开始时使用 isolated；如果 isolated 会话因空闲超时关闭，内存中的登录状态也会丢失。

**面模式的配置示例：

{
  "mcp******s": {
    "playwright": {
      "com**nd": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--headless"]
    }
  }
}

Playwright MCP 不是安全边界。测试账号应使用最低权限，涉及支付、删除、发布和权限修改的步骤应保留人工确认。不要把生产 Cookie 或存储状态提交到 Git。

给任务写明允许访问的站点、完成条件和禁止动作。先让 Claude Code查看页面和计划步骤，再允许执行会产生外部影响的操作。需要保存截图、日志或 trace 时，统一放入项目的测试产物目录并加入忽略规则。

有界面调试时使用 UU 远程连接查看浏览器；日常启动、日志检查和**面任务可通过 SSH 完成。需要保持 Claude Code 会话时，将它放入 tmux，网络断开后可以重新接回。

浏览器资料、MCP 配置、Node 环境和测试仓库都留在同一台远程 Mac 上，换本地电脑后仍可继续。系统更新或重启后，应重新执行 claude mcp list 和第一个演示任务，确认服务与浏览器都恢复正常。

ssh your-**c-mini
cd /path/to/your-project
tmux new -s playwright-mcp
claude

# 断线后接回
tmux attach -t playwright-mcp

根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，接入新加坡家庭宽带或商业宽带，支持 UU 远程、终端和多种远程连接方式。

官网公开的家庭宽带方案为每月 999 元起。长期在线的本地文件系统适合保留 Node 环境、浏览器组件、项目级 MCP 配置和测试产物；整机独享也避免与其他租户共享桌面和浏览器资料。账号、订阅和网站测试权限仍由使用者自行准备和管理。

现象	常见原因	处理建议
npx 找不到	Node.js 未安装或 PATH 未刷新	重新安装 Node.js 20 以上并重开终端
MCP 显示 disconnected	命令参数错误或首次下载失败	用 claude mcp get 检查配置并在终端单独运行 npx
首次启动很慢	正在下载浏览器组件	保持网络连接并检查可用磁盘
远程桌面看不到浏览器	使用了 headless 或桌面会话未连接	调试阶段移除 headless 并用 UU 远程查看
登录状态总是丢失	使用 isolated 或资料目录被清理	改用默认持久化配置并保护资料目录
页面操作不稳定	目标页面变化或任务描述不清	先获取新快照并把站点范围与完成条件写清