Playwright MCP

介绍

🌐 Introduction

Playwright MCP 服务器通过 模型上下文协议 提供浏览器自动化功能，使大型语言模型能够使用结构化的可访问性快照与网页交互。它可与 VS Code、Cursor、Windsurf、Claude Desktop 以及任何其他 MCP 客户端一起使用——无需视觉模型。

🌐 The Playwright MCP server provides browser automation capabilities through the Model Context Protocol, enabling LLMs to interact with web pages using structured accessibility snapshots. It works with VS Code, Cursor, Windsurf, Claude Desktop, and any other MCP client — no vision models required.

先决条件

🌐 Prerequisites

开始之前，请确保已安装以下软件：

🌐 Before you begin, make sure you have the following installed:

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

入门

🌐 Getting Started

安装

🌐 Installation

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

🌐 Add the Playwright MCP server to your client using the standard configuration:

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

VS Code

点击下面的其中一个按钮直接安装：

🌐 Click one of the buttons below to install directly:

或者通过 VS Code CLI 安装：

🌐 Or install via the VS Code CLI:

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

光标

🌐 Cursor

或者转到 Cursor Settings → MCP → Add new MCP Server 并使用带有 npx @playwright/mcp@latest 的命令类型。

🌐 Or go to Cursor Settings → MCP → Add new MCP Server and use command type with npx @playwright/mcp@latest.

克劳德代码

🌐 Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude 桌面

🌐 Claude Desktop

按照 MCP 安装指南进行，并使用上面的标准配置。

🌐 Follow the MCP install guide and use the standard config above.

其他客户

🌐 Other clients

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

🌐 The standard configuration works with most MCP clients, including Windsurf, Cline, Goose, Kiro, Codex, Copilot CLI, and others. Consult your client's MCP documentation for where to place the config.

第一次互动

🌐 First interaction

一旦服务器连接，要求你的 AI 助手与网页进行交互：

🌐 Once the server is connected, ask your AI assistant to interact with a web page:

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

助手将使用 Playwright MCP 工具打开浏览器、导航到页面，并与元素进行交互——所有操作都通过结构化的可访问性快照而不是截图完成。

🌐 The assistant will use Playwright MCP tools to open the browser, navigate to the page, and interact with elements — all through structured accessibility snapshots rather than screenshots.

核心功能

🌐 Core Features

无障碍快照

🌐 Accessibility snapshots

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

🌐 Playwright MCP operates on the page's accessibility tree, not pixels. When a tool runs, it returns a structured snapshot showing the page elements, their roles, and text content. The LLM uses element references from these snapshots to interact with the page:

- 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勾选复选框。

🌐 The LLM reads this snapshot and uses ref=e5 to type into the textbox or ref=e10 to check the checkbox.

与页面互动

🌐 Interacting with pages

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

🌐 Playwright MCP provides tools for all common browser interactions:

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

运行 Playwright 代码

🌐 Running Playwright code

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

🌐 For complex interactions that go beyond individual tool calls, use the browser_run_code tool to execute Playwright scripts directly:

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

网络监控和模拟

🌐 Network monitoring and mocking

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

🌐 Inspect network traffic and mock API responses:

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

存储状态

🌐 Storage state

保存和恢复浏览器状态，包括 cookies 和本地存储：

🌐 Save and restore browser state including cookies and localStorage:

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

配置

🌐 Configuration

有头模式

🌐 Headed mode

默认情况下，Playwright MCP 以有界模式运行浏览器，这样你可以看到发生了什么。要以无头模式运行：

🌐 By default, Playwright MCP runs the browser in headed mode so you can see what's happening. To run headless:

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

浏览器选择

🌐 Browser selection

选择要使用的浏览器：

🌐 Choose which browser to use:

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

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

🌐 Supported values: chrome, firefox, webkit, msedge.

用户资料

🌐 User profile

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

🌐 Playwright MCP supports three profile modes:

• 持久 (默认)：登录状态和 Cookies 会在各会话之间保留。配置文件存储在你平台缓存目录的 ms-playwright/mcp-{channel}-profile 中。可使用 --user-data-dir 覆盖。
• 独立：每个会话从头开始。传入 --isolated 以启用。你可以使用 --storage-state 加载初始状态。
• 浏览器扩展程序：通过 Playwright 扩展程序 连接到你现有的浏览器标签页。传递 --extension 以启用。

配置文件

🌐 Configuration file

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

🌐 For advanced configuration, use a JSON config file:

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

配置文件支持浏览器选项、上下文选项、网络规则、超时等。完整的架构请参见 Playwright MCP 仓库。

🌐 The config file supports browser options, context options, network rules, timeouts, and more. See the Playwright MCP repository for the full schema.

独立服务器

🌐 Standalone server

在没有显示器的系统上或从 IDE 工作进程运行带界面的浏览器时，请单独启动带有 HTTP 传输的 MCP 服务器：

🌐 When running a headed browser on a system without a display or from IDE worker processes, start the MCP server separately with HTTP transport:

npx @playwright/mcp@latest --port 8931

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

🌐 Then point your MCP client to the HTTP endpoint:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

快速参考

🌐 Quick Reference

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

下一步是什么

🌐 What's Next

• 使用 Web 优先断言、页面夹具和定位器编写测试
• 在 CI 上运行你的测试
• 了解有关追踪查看器的更多信息