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

如何设置 Playwright MCP 服务器 (2026)

本指南将带你完成 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 客户端有空闲超时设置。如果浏览器空闲时间过长，服务器可能会断开连接。重启对话以重新连接。

总结

如果你的项目涉及 AI 生成的媒体（如图像、视频或数字人），请查看 Hypereal AI，它提供了一个统一的 API，通过按需付费的方式处理所有媒体生成。

免费试用 Hypereal AI —— 提供 35 个积分，无需信用卡。

开始使用 Hypereal 构建

如何设置 Playwright MCP 服务器 (2026)

什么是 Playwright MCP 服务器？

为什么使用 Playwright MCP 而不是手动测试？

前提条件

第 1 步：安装 Playwright MCP 服务器

第 2 步：配置 Claude Desktop

在有头模式下运行（显示浏览器窗口）

指定浏览器

第 3 步：配置 Cursor

第 4 步：配置 Cline (VS Code)

第 5 步：配置 Claude Code (CLI)

可用的 MCP 工具

实际应用用例

测试 Web 应用程序

抓取文档

视觉回归测试

自动化表单测试

高级配置

使用自定义用户数据目录

设置自定义视口

生成 Playwright 测试代码

故障排除

总结

相关文章

Cursor AI 最佳 MCP 服务器推荐 (2026)

如何从零开始构建 MCP Server (2026)

如何使用 Claude Chrome DevTools MCP Server (2026)

立即开始构建

开始使用 Hypereal 构建

如何设置 Playwright MCP 服务器 (2026)

什么是 Playwright MCP 服务器？

为什么使用 Playwright MCP 而不是手动测试？

前提条件

第 1 步：安装 Playwright MCP 服务器

第 2 步：配置 Claude Desktop

在有头模式下运行（显示浏览器窗口）

指定浏览器

第 3 步：配置 Cursor

第 4 步：配置 Cline (VS Code)

第 5 步：配置 Claude Code (CLI)

可用的 MCP 工具

实际应用用例

测试 Web 应用程序

抓取文档

视觉回归测试

自动化表单测试

高级配置

使用自定义用户数据目录

设置自定义视口

生成 Playwright 测试代码

故障排除

总结

相关文章

Cursor AI 最佳 MCP 服务器推荐 (2026)

如何从零开始构建 MCP Server (2026)

如何使用 Claude Chrome DevTools MCP Server (2026)

立即开始构建