跳转到主要内容

Playwright MCP

简介​

Playwright MCP 服务器通过 Model Context Protocol 提供浏览器自动化功能，使 LLM 能够使用结构化可访问性快照与网页进行交互。它适用于 VS Code、Cursor、Windsurf、Claude Desktop 和任何其他 MCP 客户端 — 无需视觉模型。

先决条件​

在开始之前，请确保已安装以下内容

  • Node.js 18 或更高版本
  • 一个 MCP 客户端：VS Code、Cursor、Windsurf、Claude Code、Claude Desktop 或类似客户端

入门指南​

安装​

使用标准配置将 Playwright MCP 服务器添加到您的客户端

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

VS Code​

点击下方按钮直接安装

Install in VS Code Install in VS Code Insiders

或者通过 VS Code CLI 安装

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

Cursor​

Install in Cursor

或前往 Cursor Settings → MCP → Add new MCP Server，并使用命令 npx @playwright/mcp@latest。

Claude Code​

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop​

遵循 MCP 安装指南，并使用上述标准配置。

其他客户端​

标准配置适用于大多数 MCP 客户端，包括 Windsurf、Cline、Goose、Kiro、Codex、Copilot CLI 等。请查阅您客户端的 MCP 文档以了解配置文件的放置位置。

首次交互​

服务器连接后，请您的 AI 助手与网页进行交互

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

助手将使用 Playwright MCP 工具打开浏览器、导航到页面并与元素交互 — 所有这些都通过结构化可访问性快照而非屏幕截图完成。

核心功能​

可访问性快照​

Playwright MCP 在页面的可访问性树上操作，而不是像素。当工具运行时，它会返回一个结构化快照，显示页面元素、它们的角色和文本内容。LLM 使用这些快照中的元素引用与页面交互。

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

LLM 读取此快照并使用 ref=e5 在文本框中输入或使用 ref=e10 选中复选框。

与页面交互​

Playwright MCP 提供所有常见浏览器交互的工具

  • 导航：打开 URL、前进/后退、重新加载页面。
  • 点击和输入：点击元素、输入文本、填写表单、选择下拉菜单。
  • 屏幕截图：捕获当前页面或特定元素以进行视觉验证。
  • 键盘和鼠标：按下按键、悬停、拖放。
  • 对话框：接受或关闭浏览器对话框。
  • 标签页：创建、关闭和切换浏览器标签页。

运行 Playwright 代码​

对于超出单个工具调用的复杂交互，请使用 browser_run_code 工具直接执行 Playwright 脚本。

Run this Playwright code to verify the todo count:
async (page) => {
  const count = await page.getByTestId('todo-count').textContent();
  return count;
}

网络监控和模拟​

检查网络流量并模拟 API 响应

  • 查看网络请求：列出自页面加载以来发出的所有请求。
  • 模拟路由：设置 URL 模式匹配以返回自定义响应。
  • 控制台消息：访问浏览器控制台输出进行调试。

存储状态​

保存和恢复浏览器状态，包括 cookie 和 localStorage

  • 保存状态：将认证和会话数据持久化到文件。
  • 恢复状态：将之前保存的状态加载到新会话中。
  • Cookie 管理：列出、获取、设置和删除单个 Cookie。

配置​

有头模式​

默认情况下，Playwright MCP 在有头模式下运行浏览器，以便您可以看到正在发生的事情。要在无头模式下运行

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

浏览器选择​

选择要使用的浏览器

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

支持的值：chrome、firefox、webkit、msedge。

用户配置文件​

Playwright MCP 支持三种配置文件模式

  • 持久化（默认）：登录状态和 cookie 在会话之间保留。配置文件存储在您平台的缓存目录中的 ms-playwright/mcp-{channel}-profile 中。使用 --user-data-dir 覆盖。
  • 隔离：每个会话都是全新的。传递 --isolated 以启用。您可以使用 --storage-state 加载初始状态。
  • 浏览器扩展：使用 Playwright MCP Bridge 扩展连接到您现有的浏览器标签页。传递 --extension 以启用。

配置文件​

对于高级配置，请使用 JSON 配置文件

npx @playwright/mcp@latest --config path/to/config.json

配置文件支持浏览器选项、上下文选项、网络规则、超时等。请参阅 Playwright MCP 存储库以获取完整架构。

独立服务器​

在没有显示器或从 IDE worker 进程的系统上运行有头浏览器时，请使用 HTTP 传输单独启动 MCP 服务器

npx @playwright/mcp@latest --port 8931

然后将您的 MCP 客户端指向 HTTP 端点

{
  "mcpServers": {
    "playwright": {
      "url": "https://:8931/mcp"
    }
  }
}

快速参考​

操作如何操作
安装服务器将标准配置添加到您的 MCP 客户端
导航到页面询问："转到 https://example.com"
点击元素询问："点击提交按钮"
填写表单询问："在电子邮件字段中填写 test@example.com"
截屏询问："截取页面屏幕截图"
运行 Playwright 代码询问："运行此 Playwright 代码：..."
模拟 API询问："模拟 /api/users 端点以返回 ..."
使用有头模式默认。传递 --headless 以禁用。
选择浏览器在参数中传递 --browser=firefox

接下来​