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 20 或更新版本
• 一个 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_unsafe 工具直接执行 Playwright 脚本。该工具在 Playwright 服务器进程中运行任意 JavaScript，并具有等同远程代码执行（RCE）的能力 — 仅为受信任的 MCP 客户端启用它：

🌐 For complex interactions that go beyond individual tool calls, use the browser_run_code_unsafe tool to execute Playwright scripts directly. This tool runs arbitrary JavaScript in the Playwright server process and is RCE-equivalent — only enable it for trusted MCP clients:

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。

WebMCP 工具

🌐 WebMCP tools

页面可以通过实验性的 WebMCP API 为代理注册自己的工具。当前标签页的工具会作为名为 webmcp_<tool> 的 MCP 工具提供。

🌐 Pages can register their own tools for agents through the experimental WebMCP API. The tools of the current tab are offered as MCP tools named webmcp_<tool>.

工具名称、描述、模式和结果都是页面提供的，所以把它们当作不可靠的输入来看。

🌐 Tool names, descriptions, schemas and results are provided by the page, so treat them as untrusted input.

配置

🌐 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}-{workspace-hash} 中，因此不同项目会自动获得独立的配置文件。可以使用 --user-data-dir 覆盖。
• 独立：每个会话从头开始。传入 --isolated 以启用。你可以使用 --storage-state 加载初始状态。
• 浏览器扩展程序：通过 Playwright 扩展程序 连接到你现有的浏览器标签页。传递 --extension 以启用。

空闲超时

🌐 Idle timeout

一个持续进行动画或渲染的页面会在浏览器打开期间一直消耗 CPU，而且一个代理会话可能会持续数小时。因此，由服务器启动的无头浏览器如果一小时内没有工具调用，就会被关闭。有界面浏览器，以及通过 --cdp-endpoint 或 --extension 连接的浏览器，永远不会自动关闭。传入 --idle-timeout 可以设置任何模式下的超时时间（毫秒），或者传入 0 来禁用它：

🌐 A page that keeps animating or rendering costs CPU for as long as the browser is open, and an agent session can last hours. A headless browser launched by the server is therefore closed after an hour without tool calls. Headed browsers, and browsers attached over --cdp-endpoint or --extension, are never closed automatically. Pass --idle-timeout to set the timeout in milliseconds for any mode, or 0 to disable it:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--idle-timeout=300000"
      ]
    }
  }
}

当长时间没有工具调用完成时，浏览器会被关闭，不管是启动状态还是其他，就像你手动关闭它一样。下一次工具调用会启动一个新的浏览器，所以代理会重新导航。计时器在工具调用运行时永远不会触发。

🌐 When no tool call has completed for that long, the browser is closed, headed or not, the same way as if you had closed it by hand. The next tool call launches a new browser, so the agent navigates again. The timer never fires while a tool call is running.

• 使用 --isolated 时，保存在内存中的 cookies 和存储在空闲关闭时会丢失。使用持久化配置文件或 --storage-state 可以保留它们。
• 使用 --cdp-endpoint 或 --extension 时，浏览器不属于服务器，所以没有默认超时，而且显式设置的超时只会断开连接，但页面仍然保持打开状态。使用 --extension 时，下一个工具调用会再次通过连接流程。
• 使用 --shared-browser-context，计时器会覆盖所有客户端：当有的客户端闲置而其他客户端仍在工作时，闲置的客户端会保留其标签页和状态，只有当每个客户端都闲置达到超时时，共享浏览器才会被关闭。

配置文件

🌐 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

HTTP 会话使用五秒的心跳超时。如果你的 MCP 客户端或代理没有响应服务器发起的 ping，请将 PLAYWRIGHT_MCP_PING_TIMEOUT_MS 设置为更长的超时时间（毫秒）。将其设置为 0 可禁用心跳。

🌐 HTTP sessions use a five-second heartbeat timeout. If your MCP client or proxy does not answer server-initiated pings, set PLAYWRIGHT_MCP_PING_TIMEOUT_MS to a longer timeout in milliseconds. Set it to 0 to disable the heartbeat.

然后将你的 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 上运行你的测试
• 了解有关追踪查看器的更多信息