项目概述
Playwright MCP 通过结构化可访问性快照为 LLM 提供浏览器自动化功能，无需截图或视觉模型，实现快速、可靠的网页交互。
核心特性
基于 Playwright 强大的浏览器自动化能力，为 AI 模型提供专业的网页操作工具
快速轻量
使用 Playwright 的可访问性树而非像素级输入，提供更快的响应速度和更低的资源消耗。
LLM 友好
无需视觉模型，完全基于结构化数据操作，让 AI 模型能够准确理解和操作网页元素。
确定性操作
避免基于截图方法的模糊性，提供精确、可重复的工具应用和网页交互。
跨浏览器支持
支持 Chromium、Firefox、WebKit 等现代浏览器引擎，提供一致的自动化体验。
丰富的工具集
提供完整的浏览器操作工具：点击、输入、导航、截图、PDF 生成等功能。
移动端支持
支持移动设备模拟，可测试响应式设计和移动端专属功能。
快速配置 MCP 服务器
只需简单的 JSON 配置，即可在各种 MCP 客户端中启用 Playwright 浏览器自动化功能。
- 支持 VS Code、Cursor、Claude Desktop 等客户端
- 一键安装，无需复杂配置
- 即时可用的浏览器自动化能力
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}安装指南
选择适合你的安装方式，快速开始使用 Playwright MCP
VS Code
使用 VS Code CLI 或扩展市场一键安装，与 GitHub Copilot 完美集成。
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
Cursor
在 Cursor 设置中添加 MCP 服务器，或使用一键安装按钮快速配置。
Claude Desktop
按照 MCP 安装指南配置 Claude Desktop，享受 AI 驱动的浏览器自动化。
强大的工具集
提供完整的浏览器自动化工具，满足各种网页操作需求
交互操作
点击、输入、拖拽、悬停等基础交互操作，支持精确的元素定位和操作。
页面导航
URL 导航、前进后退、标签页管理，提供完整的浏览器导航控制。
内容捕获
截图、PDF 生成、页面快照，支持全页面和元素级别的内容捕获。
页面分析
网络请求监控、控制台消息获取、页面结构分析等调试功能。
等待机制
智能等待元素出现或消失，确保操作的可靠性和稳定性。
测试生成
自动生成 Playwright 测试代码，将手动操作转换为可重复的自动化测试。
技术架构
基于现代化技术栈构建，提供稳定可靠的浏览器自动化服务
Playwright 引擎
基于微软 Playwright 框架，支持 Chromium、Firefox、WebKit 三大浏览器引擎，提供跨平台一致性体验。
MCP 协议
完全实现 Model Context Protocol 标准，为 AI 模型提供标准化的工具接口和通信机制。
TypeScript 开发
使用 TypeScript 开发，提供完整的类型安全、智能提示和更好的开发体验。
多传输协议
支持 stdio、HTTP 和扩展模式等多种传输协议，适应不同的部署环境。
双模式架构
提供 Snapshot 和 Vision 两种工作模式，满足不同场景需求
Snapshot 模式（默认）
使用可访问性树进行页面分析，提供结构化的页面快照：
- 基于 DOM 结构和可访问性信息
- 更快的响应速度和更低的资源消耗
- 精确的元素定位和操作
- 无需视觉模型支持
Vision 模式
使用截图进行视觉分析，适合复杂的视觉交互：
- 基于页面截图的视觉分析
- 支持复杂的视觉元素识别
- 鼠标坐标精确定位
- 适合图形化界面操作
完整工具清单
提供 26+ 个专业工具，覆盖浏览器自动化的各个方面
交互操作工具
browser_click- 元素点击browser_type- 文本输入browser_drag- 拖拽操作browser_hover- 鼠标悬停browser_press_key- 按键操作browser_select_option- 选项选择
导航控制工具
browser_navigate- 页面导航browser_navigate_back- 后退browser_navigate_forward- 前进browser_tab_new- 新建标签页browser_tab_close- 关闭标签页browser_tab_select- 切换标签页
内容捕获工具
browser_snapshot- 页面快照browser_take_screenshot- 截图browser_pdf_save- PDF 生成browser_console_messages- 控制台日志browser_network_requests- 网络请求
等待与同步工具
browser_wait_for- 元素等待browser_handle_dialog- 对话框处理browser_file_upload- 文件上传browser_resize- 窗口调整browser_close- 浏览器关闭
测试与调试工具
browser_generate_playwright_test- 测试生成browser_install- 浏览器安装- 网络请求监控和分析
- 控制台消息捕获
- 错误日志收集
高级配置工具
- 浏览器引擎选择（Chromium/Firefox/WebKit）
- 用户数据目录管理
- 网络拦截和过滤
- 追踪和调试模式
- 扩展模式支持
高级配置选项
丰富的配置选项，满足各种复杂的部署和使用场景
完整配置示例
支持浏览器选择、网络控制、调试模式等多种高级配置选项。
- 多浏览器引擎支持
- 网络请求过滤
- 用户数据持久化
- 调试和追踪功能
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--browser", "chromium",
"--user-data-dir", "./browser-data",
"--save-trace",
"--allowed-origins", "https://example.com",
"--caps", "core,testing"
]
}
}
}实际使用示例
通过具体示例了解如何使用 Playwright MCP 进行浏览器自动化
网页数据抓取示例
使用 AI 助手自动抓取网页数据的完整流程：
AI：我来帮你获取 Microsoft Playwright 项目的 Stars 数量。
1. 使用 browser_navigate 导航到项目页面
2. 使用 browser_snapshot 获取页面结构
3. 定位 Stars 数量元素并提取数据
结果：Microsoft Playwright 项目当前有 65.8k Stars
自动化测试生成示例
AI 助手自动生成 Playwright 测试代码：
AI：我来为你生成登录功能的测试。
1. 使用 browser_generate_playwright_test 工具
2. 执行实际的登录步骤
3. 生成完整的 TypeScript 测试代码
结果：生成包含完整断言的 Playwright 测试文件
API 参考文档
详细的工具参数说明和使用方法
核心交互 API
browser_click
element: 要点击的元素描述ref: 元素的可访问性引用- 支持各种点击修饰符
browser_type
text: 要输入的文本内容element: 目标输入元素submit: 是否自动提交
导航控制 API
browser_navigate
url: 目标 URL 地址- 自动等待页面加载完成
- 支持相对和绝对路径
browser_wait_for
element: 等待的元素state: 等待状态（visible/hidden）timeout: 超时时间
数据捕获 API
browser_snapshot
- 无参数，返回完整页面快照
- 包含可访问性树结构
- 提供元素引用信息
browser_take_screenshot
fullPage: 是否全页截图element: 特定元素截图- 返回 base64 编码图片
配置参数 API
启动参数
--browser: 浏览器类型--vision: 启用视觉模式--user-data-dir: 用户数据目录--save-trace: 保存执行追踪
网络控制
--allowed-origins: 允许的域名--blocked-origins: 阻止的域名--caps: 启用的功能集
最佳实践指南
掌握这些最佳实践，让你的浏览器自动化更加高效可靠
性能优化
- 优先使用 Snapshot 模式而非 Vision 模式
- 合理设置等待超时时间
- 使用网络过滤减少不必要的请求
- 及时关闭不需要的标签页
稳定性保障
- 使用明确的元素选择器
- 添加适当的等待机制
- 处理弹窗和对话框
- 实现错误重试机制
安全考虑
- 限制访问的域名范围
- 使用独立的用户数据目录
- 避免在生产环境运行不受信任的代码
- 定期清理临时文件和缓存
调试技巧
- 启用追踪模式记录操作步骤
- 使用控制台消息工具查看日志
- 监控网络请求排查问题
- 保存截图辅助问题定位
社区与支持
加入活跃的开发者社区，获取帮助和分享经验