Playwright MCP 浏览器自动化实战指南

Playwright MCP 浏览器自动化实战指南

整理日期： 2026-06-03

简介

Playwright MCP 是 Microsoft 官方维护 的浏览器自动化 MCP 服务器。它通过 Model Context Protocol（MCP）将 Playwright 浏览器的全部能力暴露给 AI 编程助手，让 AI 能够像人类一样操作浏览器——导航页面、点击按钮、填写表单、截图、执行 JavaScript。

与传统的浏览器自动化方案不同，Playwright MCP 使用 无障碍树（Accessibility Tree） 而非像素坐标来定位元素，这让 AI 能够通过语义理解页面结构，操作更加精准和稳定。

核心优势：

• 🏆 Microsoft 官方维护，与 Playwright 主项目同步更新
• 🔧 跨浏览器支持 —— Chromium、Firefox、WebKit 三大引擎
• 📱 移动端模拟 —— 模拟 iPhone、Android 设备
• 🎯 无障碍树定位 —— LLM 友好，无需 XPath/CSS 选择器
• 🚀 零配置启动 —— npx 一键运行，自动下载浏览器

---

前置要求

依赖	版本要求	说明
Node.js	>= 18	Playwright MCP 通过 npx 运行
AI CLI	Claude Code / Hermes Agent 等	支持 MCP 协议的 AI 编程工具
网络	可访问 npm registry	首次运行自动下载浏览器（~300MB）

推荐环境检查：

node --version
# v18.x 或更高

# 确认 AI CLI 已安装
claude --version

---

一、安装与配置

1.1 在 Claude Code 中安装

# 方式一：使用 claude mcp add 命令（推荐）
claude mcp add playwright -s local -- npx @playwright/mcp@latest

# 方式二：全局作用域，所有项目可用
claude mcp add playwright -s user -- npx @playwright/mcp@latest

1.2 在 Hermes Agent 中配置

编辑 ~/.hermes/config.yaml：

mcp_servers:
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
    timeout: 120
    connect_timeout: 60

然后重启 Hermes Agent。启动时会自动连接 Playwright MCP，工具会自动注册。

1.3 手动配置文件方式

创建 .mcp.json（项目级）或 ~/.mcp.json（用户级）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

1.4 验证安装

# 查看已安装的 MCP 服务器
claude mcp list

# 输出应包含 playwright
# playwright → npx @playwright/mcp@latest [local]

首次运行时会自动下载 Chromium 浏览器二进制文件，后续启动秒级完成。

---

二、工具清单与功能详解

Playwright MCP 提供约 20 个工具，按功能分组如下：

2.1 页面导航

工具名	功能	参数
browser_navigate	导航到指定 URL	url: 目标地址
browser_go_back	浏览器后退	无参数
browser_go_forward	浏览器前进	无参数
browser_reload	刷新页面	无参数

示例：

claude "打开 https://example.com 并截图"

AI 内部调用：

browser_navigate(url: "https://example.com")
browser_screenshot()

2.2 页面交互

工具名	功能	参数
browser_click	点击元素	element: 无障碍树元素描述
browser_fill	填写输入框	element, value: 填入的文本
browser_select_option	选择下拉选项	element, value: 选项值
browser_hover	鼠标悬停	element
browser_press_key	按键操作	key: 键盘按键名
browser_drag_and_drop	拖拽操作	source_element, target_element

示例：

claude "帮我登录这个网站：打开 https://example.com/login，输入用户名 admin，密码 123456，然后点击登录按钮"

AI 内部调用链路：

1. browser_navigate(url: "https://example.com/login")
2. browser_fill(element: "用户名输入框", value: "admin")
3. browser_fill(element: "密码输入框", value: "123456")
4. browser_click(element: "登录按钮")

2.3 内容获取

工具名	功能	参数
browser_screenshot	页面截图	full_page: 是否全页截图
browser_get_content	获取页面文本内容	无参数
browser_get_element_text	获取指定元素文本	element
browser_get_attribute	获取元素属性	element, attribute

2.4 多标签管理

工具名	功能	参数
browser_new_page	新建标签页	url: 可选，新标签页地址
browser_close_page	关闭当前标签页	无参数
browser_switch_page	切换标签页	page_id: 标签页 ID
browser_list_pages	列出所有标签页	无参数

示例：多标签操作

claude "打开百度搜索'天气'，再打开新标签页搜索'新闻'，然后把两个结果截图"

2.5 高级功能

工具名	功能	参数
browser_evaluate	执行 JavaScript	script: JS 代码段
browser_get_cookies	读取 Cookie	无参数
browser_set_cookies	设置 Cookie	cookies: Cookie 数组
browser_clear_cookies	清除 Cookie	无参数
browser_take_snapshot	获取无障碍树快照	无参数（AI 自动使用）

---

三、实战案例

案例 1：自动抓取新闻标题

需求：打开 Hacker News，提取首页前 10 条新闻标题和链接。

claude "打开 https://news.ycombinator.com，提取首页前10条新闻的标题和链接，以表格形式返回"

AI 执行过程：

1. browser_navigate(url: "https://news.ycombinator.com")
2. browser_get_content() → 获取页面文本
3. 解析标题行和链接行
4. 生成 Markdown 表格

预期输出：

| # | 标题 | 链接 |
|---|------|------|
| 1 | Show HN: Example Project | https://news.ycombinator.com/item?id=xxx |
| 2 | ... | ... |

案例 2：表单填写与提交流程测试

需求：测试一个用户注册流程，填写表单并提交。

claude "打开 https://example.com/register，帮我完成用户注册表单：
1. 用户名：test_user_001
2. 邮箱：test@example.com
3. 密码：Test@123456
4. 确认密码：Test@123456
5. 勾选同意条款
6. 点击注册按钮
然后截图告诉我是否注册成功"

案例 3：跨标签搜索引擎比价

需求：在多个电商平台搜索同一商品比价。

claude "帮我比价 iPhone 16 Pro Max：
1. 打开淘宝搜索 'iPhone 16 Pro Max'
2. 新建标签页打开京东搜索同款
3. 切换到淘宝截图搜索结果
4. 切换到京东截图搜索结果
5. 汇总两个平台的最低价格"

案例 4：执行 JavaScript 获取页面状态

claude "打开 https://example.com，执行以下 JavaScript 并返回结果：
1. 获取页面所有图片的 src
2. 检查页面是否有 404 资源
3. 获取页面加载性能数据（performance.timing）"

AI 内部调用：

browser_navigate(url: "https://example.com")
browser_evaluate(script: "Array.from(document.images).map(img => img.src)")
browser_evaluate(script: "performance.getEntriesByType('resource').filter(e => e.responseStatus >= 400)")
browser_evaluate(script: "JSON.stringify(performance.timing)")

案例 5：Cookie 管理操作

claude "登录 https://example.com，获取登录后的 Cookie 信息，保存到文件"

AI 内部调用：

browser_navigate(url: "https://example.com/login")
browser_fill(element: "用户名", value: "myuser")
browser_fill(element: "密码", value: "mypass")
browser_click(element: "登录按钮")
browser_get_cookies() → 返回 Cookie 数组

---

四、配置自定义选项

4.1 使用指定浏览器

mcp_servers:
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
    env:
      PLAYWRIGHT_CHROMIUM_EXECUTABLE: "/usr/bin/chromium-browser"  # 指定 Chromium 路径

4.2 启动选项

# 使用 Chrome 而非默认 Chromium
claude mcp add playwright -- npx @playwright/mcp@latest --browser=chrome

# 无头模式（默认）
claude mcp add playwright -- npx @playwright/mcp@latest --headless

# 显示浏览器窗口（调试用）
claude mcp add playwright -- npx @playwright/mcp@latest --visible

4.3 设置页面视口大小

通过环境变量配置默认视口：

mcp_servers:
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
    env:
      PLAYWRIGHT_VIEWPORT_WIDTH: "375"    # iPhone 宽度
      PLAYWRIGHT_VIEWPORT_HEIGHT: "812"   # iPhone 高度

4.4 代理配置

mcp_servers:
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
    env:
      PLAYWRIGHT_PROXY: "http://proxy.example.com:8080"

---

五、Playwright MCP vs 其他浏览器方案

对比维度	Playwright MCP	Chrome DevTools MCP	Puppeteer MCP
维护方	Microsoft	Google	社区
浏览器支持	Chromium + Firefox + WebKit	仅 Chrome	仅 Chromium
核心能力	自动化操作	调试诊断	自动化操作
工具数量	~20 个	29 个	~15 个
无障碍树	✅ 原生支持	❌ 无	❌ 无
多标签页	✅	❌	✅ (有限)
Console 读取	✅ 基础	✅✅✅ 完整	❌
性能分析	❌	✅✅✅	❌
网络拦截	✅ 完整	✅✅✅ 完整	✅ 基础
启动方式	自启动	连接已有 Chrome	自启动
AI 友好度	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐

---

六、常见问题与故障排查

Q1：首次运行提示 "Cannot find browser"

原因：Playwright 尚未下载浏览器二进制文件。

解决：

# 手动安装浏览器
npx playwright install chromium

# 或安装全部浏览器
npx playwright install

Q2：页面操作报 "Element not found"

原因：AI 通过无障碍树定位元素失败。

解决：

• 尝试更具体地描述元素："点击页面中央那个蓝色的'登录'按钮"
• 要求 AI 先截图，再基于截图描述操作
• 使用 browser_take_snapshot 获取无障碍树结构

Q3：截图内容为空白

原因：页面加载未完成或需要滚动。

解决：

# 要求 AI 等待页面加载完成后再截图
claude "打开页面后等待5秒再截图"

Q4：Cookie 无法设置

原因：Cookie 域名与当前页面域名不匹配。

解决：确保先导航到目标域名后再设置 Cookie。

Q5：多标签页操作混淆

原因：AI 在同一会话中同时操作多个标签页时上下文混乱。

解决：分步执行，每次操作后确认当前标签页状态。

---

七、安全注意事项

## Playwright MCP 安全指南

✅ **允许的操作：**
- 访问公开网页、提取信息
- 自动化表单测试（测试环境）
- 截图保存页面状态
- 执行只读 JavaScript

❌ **禁止的操作：**
- 不要在生产环境输入真实密码
- 不要自动执行敏感操作（转账、删除）
- 不要将 Cookie 暴露给不信任的 AI 提示
- 不要爬取违反 robots.txt 的页面

**最佳实践：**
1. 测试环境使用独立的测试账号
2. 敏感操作需要人工确认
3. 使用 `--headless` 模式避免界面干扰
4. 定期清理浏览器缓存和 Cookie

---

八、总结

Playwright MCP 是当前 AI 浏览器自动化领域的最佳选择。它解决了传统浏览器自动化工具的几个核心痛点：

痛点	Playwright MCP 的解决方案
元素定位困难	无障碍树语义定位，无需 XPath/CSS
跨浏览器兼容	原生支持三大浏览器引擎
AI 集成复杂	MCP 标准协议，一行命令集成
上下文管理	自动截图 + 内容提取辅助 AI 理解

适用场景：

• ✅ 网页数据抓取和监控
• ✅ 端到端测试自动化
• ✅ 表单填写和提交验证
• ✅ 多平台比价和信息聚合
• ✅ 页面状态检查和性能验证
• ✅ 跨浏览器布局对比

快速开始命令：

# 一分钟上手
claude mcp add playwright -s local -- npx @playwright/mcp@latest
claude "打开 https://example.com 截图"

---

本文基于最新会话讨论内容整理，部分信息参考 Microsoft Playwright MCP 官方文档。