如何设置 Playwright MCP Server (2026)

如何设置 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 个积分，无需信用卡。