内容
# playwright-mcp
一键安装，每个 Claude Code 项目都拥有一个真正的浏览器。页面抓取附带引用，网站调试附带持久登录，并且底层使用完整的 Playwright 工具集。只需在用户范围内连接一次，即可不再思考。
## 什么是 playwright-mcp
一个 MCP 服务器，封装了 `@playwright/mcp` 并添加了四个自己的工具。安装程序拒绝 Claude 内置的 WebFetch 和 claude-in-chrome 扩展，因此 `web_fetch` 成为 Claude 唯一的页面抓取路径。额外功能免费附带。
### playwright-mcp 的工作原理
Claude 内置的 WebFetch 只返回页面文本。
当该服务器接管该工作时，每个抓取请求都附带结构化的引用元数据（作者、日期、出版商，以 CSL-JSON 格式），页面健康状态分类（付费墙、软 404、停放、登录墙、阻止）和 CMS 检测。Claude 不需要这些信息，它们已经存在于页面摘要或引用时。
内置功能无法实现的另一件事是渲染。单页面应用、重度 JavaScript 仪表盘、同意墙后的页面。`web_fetch` 运行一个真正的无头 Chromium，带有隐身上下文，因此它看到的是用户看到的内容。
该服务器与网页搜索无关。Claude 在 Anthropic 的基础设施上运行自己的原生 WebSearch。可选的导航指令由安装程序添加到 `~/.claude/CLAUDE.md` 中，只是告诉 Claude 通过 `web_fetch` 访问搜索结果中的顶级 URL，以便在摘要时提供引用和页面健康数据。服务器处理页面访问部分，Claude 执行搜索。
### 工具
总共 27 个工具。23 个是封装的 `browser_*` 工具集（导航、快照、点击、截图等）。四个自定义工具：
- **`web_fetch`**：隐身渲染 URL（HTML 或 PDF），返回可读文本以及上述引用和健康数据。
- **`session_login`** 和 **`session_status`**：处理跨项目的身份验证调试。捕获登录会话到 mode-600 storageState 文件，然后在任意项目中重用，进行交互式调试和生成的 Playwright 测试套件。头部模式处理 2FA 和 SSO。
- **`session_scaffold_tests`**：生成一个确定性的 Playwright E2E 测试套件到任意项目，与 `session_login` 捕获的会话重用。无模型参与。只需 `npx playwright test`。
## 需求
- Node 18 或更新版本
- Claude Code CLI（`claude`）在您的 PATH 中
- 大约 170 MB 用于一次性 Chromium 下载。在 Linux 上，安装程序还会拉取 Chromium 所需的系统库，这可能需要 sudo。
## 安装
捆绑安装程序处理整个过程。检查 Node，安装依赖项，构建，下载 Chromium，在用户范围内注册服务器。它会打印全局配置的差异，您可以确切地看到发生了什么。
**Linux / macOS**
```bash
./install.sh
```
**Windows PowerShell**
```powershell
.\install.ps1
```
安装程序在 `~/.claude/settings.json` 中添加了否决规则，以通过此服务器路由页面抓取和浏览器工作（`WebFetch` 和 `mcp__claude-in-chrome`）。原生 WebSearch 保持启用。如果您从禁用 WebSearch 的早期版本升级，安装程序会为您删除过时的否决规则。它还会在 `~/.claude/CLAUDE.md` 中添加一个可选的导航注释。跳过任一操作，分别使用 `--no-deny` / `--no-steer`（PowerShell：`-NoDeny` / `-NoSteer`）。
### 手动注册
如果您不想使用安装程序，请自己构建并注册绝对路径。
```bash
npm install
```
```bash
npm run build
```
```bash
npx playwright install chromium
```
```bash
claude mcp add --scope user playwright-mcp -- node /ABSOLUTE/PATH/dist/index.js
```
### 更新
拉取最新更改并再次运行相同的安装程序。它会重建，如果版本更改，则重新下载 Chromium，并重新注册服务器。随时安全运行。
## 验证
重启 Claude Code，在任意项目中运行 `/mcp`，查找 `mcp__playwright-mcp__*` 工具。要单独检查服务器：
```bash
npm run smoke
```
完整的确定性门控（构建、测试、烟雾测试）是一个命令。
```bash
npm run gate
```
## 配置
`session_login` 的凭证存储在 `~/.config/playwright-mcp/secrets.env` 中，模式 600 且 gitignored。查看 `.env.example` 获取格式，如果您想将文件放在其他位置，请设置 `PLAYWRIGHT_MCP_SECRETS`。
如果您正在工作的项目保留自己的 `.env`，`session_login` 会先读取它。项目文件在两个文件都定义某个键时优先，只有您在 `credKeys` 中命名的键会被读取。如果文件不在项目根目录，请将 `envFile` 参数指向它。
## 身份验证端到端测试
您使用 `session_login` 捕获的会话不仅用于交互式调试。相同的 mode-600 storageState 文件也可以驱动确定性的 `npx playwright test` 套件在任意项目中。代理驱动浏览器工具来发现流程，然后您将已知路径冻结为 `.spec.ts`，由运行器重放，无需模型参与。
在项目中构建一个，无需离开。要求 Claude 调用 `session_scaffold_tests`（它在工具列表中），它会在目标目录中写入 `playwright.config.ts`、新鲜度防护设置项目、示例规范和 README。不包含会话数据，只有连接。
```text
session_scaffold_tests({ session: "<name>", outDir: "/path/to/your/project" })
```
还有一个 CLI 前门户在同一个生成器上。
```bash
npm run scaffold:e2e -- --session <name> --out /path/to/your/project
```
生成的配置从 `session_login` 写入的相同路径解析 storageState。它遵循 `PLAYWRIGHT_MCP_SESSIONS`，然后是 `XDG_CONFIG_HOME` 或 `APPDATA`，因此它在任何机器上都有效，无需硬编码的主目录。设置项目永远不会登录。它会检查捕获的会话是否存在且新鲜，如果不是，则会引导您回到 `session_login`（头部用于 2FA）。对于 CI，gitignored 会话文件不存在，请将 `STORAGE_STATE` 指向作业从掩蔽的机密生成的路径。生成的 `README.md` 中有详细信息。
## 测试套件构建器
除了基本框架外，三个 `suite_*` 工具携带完整的、与项目无关的端到端方法论 — 从运行大型生产回归测试套件中提炼 — 因此 AI 助手可以以相同的方式在任意项目中构建、维护和审计测试套件。所有项目特定内容（夹具、选择器、凭证、“测试模式”含义）保留在目标存储库中；服务器仅提供模板、剧本文本和报告解析器。
- **`suite_scaffold`**：将整个软件包写入项目：Playwright 配置与捕获的会话重用、由 `e2e-suite.config.json` 驱动的环境防护（您的测试模式上下线命令，带有生效验证）、强制页面完整性门控（渲染的服务器错误、泄漏的模板令牌、`undefined`/`NaN` 文本失败测试）、仅报告的错误捕获、会话隔离规则 — 以及生成的 `.claude/skills/test-suite/` 技能，教导 AI 该项目的运行/作者/审计纪律。
- **`suite_audit`**：运行项目的套件（`run: true`）或解析其最新的 JSON 报告（`reportPath`），并返回每个失败的档案以及裁决标准：每个失败被归类为 TEST-DEFECT（修复脚本）或 PRODUCT-BUG（报告并移交 — 永远不要放松断言以求绿色）。判断保留给模型；工具使证据廉价且结构化。
- **`suite_methodology`**：按需提供操作指南（`overview` / `methodology` / `authoring` / `audit`），从同一个文件提供，构建者安装，因此只有一个真实来源。
`suite_scaffold` 和 `suite_audit` 是本地独有的（远程拒绝列表），类似于会话工具；`suite_methodology` 在任何地方都可用。
## claude.ai 的远程连接器
上述所有内容都是本地设置。服务器通过 stdio 为您自己的机器上的 Claude Code 运行，默认情况下就是这样。除非您打开它，否则不会发生任何变化。
设置 `PLAYWRIGHT_MCP_PUBLIC_URL`，同一个服务器还会公开一个远程 Streamable-HTTP 传输，因此 claude.ai 可以将其用作自定义连接器。吸引力与此存在的原因相同。claude.ai 内置的抓取功能只读取文本。这个功能渲染 JavaScript 并实际与页面交互。
远程端是一个单独的、加固的部署，您不会在笔记本电脑上运行它。运行代码或触摸凭证的工具从 claude.ai 可以访问的内容中剥离。GitHub OAuth 将其锁定到单个登录。实例本身在没有任何机密的情况下运行。它需要 nginx、TLS 和防火墙，因此完整的演练手册位于其自己的运行手册中，[docs/REMOTE-CONNECTOR.md](docs/REMOTE-CONNECTOR.md)。
## 许可证
MIT
