如何设置 Playwright MCP Server (2026)
通过 MCP 将浏览器自动化连接至 AI 助手
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
如何设置 Playwright MCP 服务器 (2026)
Playwright MCP 服务器允许 AI 助手控制真实的浏览器——执行页面导航、点击元素、填写表单、截取屏幕截图以及运行端到端测试。你的 AI 不再仅仅是描述屏幕上看到的内容,而是可以通过 Model Context Protocol 直接与网页进行交互。
本指南将带你完成 Playwright MCP 服务器的设置,并将其连接到 Claude Desktop、Cursor、VS Code 和 Claude Code。
什么是 Playwright MCP 服务器?
Playwright MCP 服务器将 Microsoft 的 Playwright 浏览器自动化库封装在兼容 MCP 的接口中。当连接到 AI 助手时,它会开放让 AI 执行以下操作的工具:
- 导航至 URL 并与页面元素交互
- 点击按钮、填写输入框、选择选项
- 截取全屏或特定元素的截图
- 提取文本内容和页面结构
- 在浏览器上下文中执行 JavaScript
- 处理身份验证流程和多页工作流
为什么使用 Playwright MCP 而不是手动测试?
| 方法 | 速度 | 准确性 | AI 集成 | 设置 |
|---|---|---|---|---|
| Playwright MCP + AI | 快 | 高 | 原生支持 | 中等 |
| 手动浏览器测试 | 慢 | 高 | 无 | 无 |
| 截图 + AI | 快 | 低-中 | 间接 | 无 |
| Selenium 脚本 | 中 | 高 | 无 | 高 |
| Cypress | 中 | 高 | 无 | 中等 |
前提条件
| 要求 | 详情 |
|---|---|
| Node.js | v18 或更高版本 |
| npm 或 yarn | 用于安装 MCP 服务器 |
| 兼容 MCP 的客户端 | Claude Desktop, Cursor, Cline, 或 Claude Code |
| Chromium | Playwright 会安装其自带的捆绑浏览器 |
第 1 步:安装 Playwright MCP 服务器
官方 Playwright MCP 服务器由 Microsoft 维护。你可以全局安装它,或者使用 npx 直接运行:
# 选项 1:使用 npx 直接运行(推荐)
npx @playwright/mcp@latest
# 选项 2:全局安装
npm install -g @playwright/mcp
第一次运行时,Playwright 会下载浏览器二进制文件(Chromium, Firefox, WebKit)。这可能需要一分钟。
手动安装浏览器:
npx playwright install
第 2 步:配置 Claude Desktop
将 Playwright MCP 服务器添加到你的 Claude Desktop 配置文件中。
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
重启 Claude Desktop。你应该能看到代表 MCP 工具已可用的锤子图标。
在有头模式下运行(显示浏览器窗口)
默认情况下,Playwright 以无头(headless)模式运行(不显示浏览器窗口)。为了进行调试以查看浏览器:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headed"]
}
}
}
指定浏览器
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "firefox"]
}
}
}
支持的值:chromium (默认), firefox, webkit.
第 3 步:配置 Cursor
在 Cursor 的设置中添加 Playwright MCP 服务器,或者在项目根目录创建一个 .cursor/mcp.json 文件:
{
"servers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
打开 Cursor Settings > MCP 来确认服务器已连接。
第 4 步:配置 Cline (VS Code)
在 Cline 扩展设置中,进入 MCP Servers 并添加:
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
当你开始新对话时,Cline 会自动检测可用工具。
第 5 步:配置 Claude Code (CLI)
对于 Claude Code,将 Playwright MCP 服务器添加到你的全局 MCP 配置中,或者通过命令行传递:
# 直接传递 MCP 配置
claude --mcp-config playwright-mcp.json
创建一个 playwright-mcp.json 文件:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
或者将其添加到 ~/.claude/mcp_servers.json 以实现持久化访问:
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
可用的 MCP 工具
Playwright MCP 服务器向你的 AI 助手开放以下工具:
| 工具 | 描述 |
|---|---|
browser_navigate |
导航至一个 URL |
browser_click |
点击页面上的一个元素 |
browser_fill |
在输入框中输入文本 |
browser_screenshot |
截取页面截图 |
browser_select |
选择下拉菜单选项 |
browser_hover |
悬停在某个元素上 |
browser_press_key |
按下一个键盘按键 |
browser_get_text |
从元素中提取文本内容 |
browser_evaluate |
在页面中执行 JavaScript |
browser_wait |
等待某个元素出现 |
browser_close |
关闭浏览器 |
实际应用用例
测试 Web 应用程序
导航到 http://localhost:3000/login 并测试登录流程:
1. 在邮箱字段填写 "test@example.com"
2. 在密码字段填写 "password123"
3. 点击 "Sign In" 按钮
4. 截图以验证仪表盘是否已加载
5. 检查欢迎消息是否显示 "Welcome, Test User"
AI 将使用 Playwright MCP 工具执行每个步骤并报告结果。
抓取文档
前往 https://platform.openai.com/docs/api-reference/chat/create
并提取所有的请求参数、它们的类型以及描述。
将它们格式化为 TypeScript 接口。
视觉回归测试
导航到 http://localhost:3000 并截取以下页面的截图:
1. 首页的 Banner 区域
2. 价格页
3. 登录页
4. 仪表盘(使用测试凭据登录后)
将每个截图与设计规范进行对比,并报告任何视觉差异。
自动化表单测试
前往 http://localhost:3000/signup 并测试表单校验:
1. 提交空表单并截图错误提示
2. 输入无效的邮箱并检查校验情况
3. 输入少于 8 位的密码并检查
4. 正确填写所有内容并验证提交成功
高级配置
使用自定义用户数据目录
在运行之间持久化 Cookie 和会话:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--user-data-dir", "/tmp/playwright-mcp-data"
]
}
}
}
设置自定义视口
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--viewport", "1920x1080"
]
}
}
}
生成 Playwright 测试代码
一个强大的工作流是让 AI 与你的应用程序交互,然后生成可复用的 Playwright 测试脚本:
在 http://localhost:3000/shop 上完成结账流程:
1. 将产品添加到购物车
2. 前往结账
3. 填写收货详情
4. 完成购买
然后生成一个 Playwright 测试文件 (checkout.spec.ts),
用于在 CI/CD 中自动化整个流程。
AI 使用 MCP 工具与应用交互,然后根据其学到的内容编写标准的 Playwright 测试。
故障排除
"Browser failed to launch":
运行 npx playwright install 以确保浏览器二进制文件已下载。在 Linux 上,你可能还需要系统依赖项:npx playwright install-deps。
"Element not found" 错误:
网页加载可能需要时间。要求 AI 在与元素交互前使用 browser_wait。动态 SPA 通常需要显式等待。
截图是空白或黑屏:
这在某些系统的无头模式下可能会发生。尝试使用 --headed 模式运行进行调试,或确保你的 GPU 驱动程序已更新。
内存使用过高:
Playwright 浏览器实例会消耗内存。在会话之间使用 browser_close 关闭浏览器。避免同时打开过多标签页。
MCP 服务器在超时后断开连接: 某些 MCP 客户端有空闲超时设置。如果浏览器空闲时间过长,服务器可能会断开连接。重启对话以重新连接。
总结
Playwright MCP 服务器弥合了 AI 助手与真实浏览器交互之间的鸿沟。你的 AI 助手可以直接导航、交互并验证你的 Web 应用程序,而不是仅仅描述截图或手动运行测试。结合 AI 生成的测试脚本,这将成为开发和 QA 的强大工作流。
如果你的项目涉及 AI 生成的媒体(如图像、视频或数字人),请查看 Hypereal AI,它提供了一个统一的 API,通过按需付费的方式处理所有媒体生成。
免费试用 Hypereal AI —— 提供 35 个积分,无需信用卡。
