/ 目录 / 演练场 / Playwright
● 官方 microsoft ⚡ 即开即用

Playwright

作者 microsoft · microsoft/playwright-mcp

通过无障碍树驱动真实浏览器——Claude 读取结构化页面内容而非像素,所以比截图型智能体更快更可靠。

微软官方 Playwright MCP。打开浏览器(Chromium、Firefox、WebKit),导航、点击、输入、填表、拦截网络。基于无障碍树构建,Claude 直接读取语义内容——无需 OCR。

为什么要用

核心特性

实时演示

实际使用效果

playwright.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "playwright",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "playwright": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@playwright/mcp@latest"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add playwright -- npx -y @playwright/mcp@latest

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Playwright

60 秒内对生产部署做冒烟测试

👤 DevOps 工程师、发布经理 ⏱ ~5 min intermediate

何时使用: 刚刚发布了部署,想在宣布成功之前快速检查关键用户流是否仍然有效。

前置条件
  • 测试账户凭据(使用专门的 QA 账户,不要用真实用户) — 存储在环境变量或直接在 prompt 中
步骤
  1. 打开主页并验证加载
    打开 https://app.example.com。验证页面返回 200,H1 显示 'Welcome',登录按钮可见。✓ 已复制
    → 成功/失败,失败时附带截图
  2. 运行登录 → 核心操作 → 登出流
    [email protected] / [password] 登录。然后创建名为 'smoke-test-<timestamp>' 的新项目。然后删除它。然后登出。✓ 已复制
    → 每个步骤都成功;如有失败,附带截图和 DOM 转储
  3. 诊断任何失败
    如果某个步骤失败,捕获页面快照并告诉我与正常基准的区别。✓ 已复制
    → 导致破坏的特定元素或网络请求

结果: 一分钟内对部署有信心(或快速发现问题),无需完整的端到端测试套件。

注意事项
  • 硬编码的测试数据堆积并污染生产环境 — 始终在测试数据中使用唯一时间戳,并在流程结束时清理
  • 浏览器会话在运行间持续存在,掩盖需要干净状态的 bug — 使用 --browser-context: incognito 运行或在运行间清除 cookie
搭配使用: sentry

在 5 个视口宽度上审计你的网站并报告破损情况

👤 前端工程师、设计师 ⏱ ~15 min intermediate

何时使用: 在发布营销网站或产品页面前,你想验证它在常见宽度上不会破损。

步骤
  1. 在 5 个视口宽度(320、375、768、1024、1440)上打开页面
    在视口 320×568、375×812、768×1024、1024×768、1440×900 上打开 https://example.com。分别截取整页屏幕。✓ 已复制
    → 保存 5 张截图
  2. 检测每个宽度上的水平溢出
    对每个视口,列出所有 scrollWidth > viewportWidth 的元素。这些会导致水平滚动,看起来破损。✓ 已复制
    → 每个视口的违规 CSS 选择器列表
  3. 建议修复
    对每个溢出元素,获取其计算 CSS 并建议最小修复(可能是 max-width、overflow-wrap 或断点调整)。✓ 已复制
    → 每个元素的可执行 diff

结果: 一个优先化的修复列表,包含具体选择器,可作为单个 PR 提交。

注意事项
  • 真实用户有滚动条(Windows 上 15px),无头浏览器默认不模拟 — 使用 --browser=chromium 和 --browser=webkit 都测试;宽度比你想象的更重要
搭配使用: chrome-devtools · filesystem

爬取需要认证的数据

👤 数据分析师、研究者 ⏱ ~20 min advanced

何时使用: 你需要的数据在登录后(你自己的管理仪表板、内部报告等),基本爬虫无法访问。

前置条件
  • 目标的有效凭据 — 使用服务账户,永远不要用个人账户
步骤
  1. 登录
    打开 https://target.example.com/login。用 [email] 填充邮箱字段,用 [password] 填充密码。提交。✓ 已复制
    → 会话已确认——登陆到仪表板 URL
  2. 导航到数据页面
    点击进入 Reports 部分。等待数据表渲染。✓ 已复制
    → 表在 DOM 中可见
  3. 提取数据
    读取报告表的每一行。以 JSON 格式返回,每列作为一个键。✓ 已复制
    → 完整的 JSON 数据集

结果: 你无法通过简单 HTTP 爬虫获取的结构化数据,可直接导入电子表格或数据库。

注意事项
  • MFA 已启用并破坏流程 — 如果服务支持,设置特定应用密码,或改用长期 API token
  • 多次登录后出现验证码 — 使用持久浏览器上下文(--user-data-dir)以复用 cookie,避免触发验证码
搭配使用: postgres · filesystem

组合

与其他 MCP 搭配,撬动十倍杠杆

playwright + filesystem

爬取网站,将每个页面内容保存到磁盘以进行离线 RAG

从 /api 开始爬取 docs.stripe.com,将每个页面保存为 ./knowledge/stripe/{path}.md 下的 Markdown 文件。✓ 已复制
playwright + chrome-devtools

在一个流中进行性能 + 功能测试——验证页面加载正确且快速

打开我的登陆页。验证 H1,然后捕获 Lighthouse 跟踪并告诉我 LCP 是否在 2 秒以下。✓ 已复制
playwright + sentry

通过重放用户面包屑来重现 Sentry 中报告的生产错误

Sentry 问题 WEB-3a91 说用户点了 X 然后 Y 然后崩溃了。在 Playwright 中重现该确切序列并确认。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
browser_navigate url: str 导航到 URL——任何流的第一个操作 1 page load
browser_snapshot 获取所有交互元素的结构化视图(链接、按钮、输入) free
browser_click ref: str (from snapshot) | selector: str 点击由快照引用或 CSS 选择器标识的元素 free
browser_type ref, text, submit?: bool 填充输入字段;使用 submit:true 时还会按 Enter free
browser_screenshot fullPage?: bool, path?: str 捕获视觉证据——调试或审计 disk space
browser_evaluate script: str 在页面上下文中运行任意 JS——谨慎使用,优先使用具体工具 free
browser_network_requests 检查页面加载的内容;对发现隐藏 API 端点很有用 free

成本与限制

运行它的成本

API 配额
免费——在本地运行,仅占用你的机器资源
每次调用 Token 数
快照根据页面复杂度为 500-3000 token
费用
免费。浏览器二进制文件仅下载一次(~300MB Chromium)。
提示
使用 browser_snapshot 而非截图——在 token 上便宜 100 倍,Claude 更容易基于它采取行动。

安全

权限、密钥、影响范围

凭据存储: 通过环境变量传递;永远不要在 prompt 中放置真实生产凭据
数据出站: 浏览器连接到你导航到的任何 URL。没有发送给微软的遥测。

故障排查

常见错误与修复

找不到元素 / TimeoutError

页面尚未完成渲染。在操作前添加显式等待:browser_wait_for(selector)browser_wait_for(text='...')

验证: 先截取快照查看页面上实际的内容
浏览器在 Linux 上启动失败

安装 OS 依赖:npx playwright install-deps。Docker 中常见——使用官方 Playwright 镜像作为基础。

验证: playwright --version
所有导航都失败,出现 net::ERR_*

网络沙箱问题。如果在 Docker 中,使用 --no-sandbox 运行,或检查你的防火墙 / 代理。

网站检测到自动化并显示验证码

使用 --browser-type=firefox(比无头 Chromium 更难被检测),或适当地有头运行。某些网站刻意抵抗机器人——尊重这一点。

替代方案

Playwright 对比其他方案

替代方案何时用它替代权衡
puppeteer MCP你只需要 Chromium 并想要更简洁的 API仅支持 Chromium;无 Firefox/WebKit;现在社区较小
Firecrawl MCP你只需要提取内容,无需与页面交互托管的(需要花费积分)但无基础设施;无法点击遍历流程
Browserbase MCP你需要从无服务器上下文运行浏览器自动化(无本地浏览器)托管服务,按分钟计费;适合生产环境智能体

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills