首页
/ Playwright MCP 完全指南：让 LLM 通过无障碍快照操作浏览器——安装、工具集与配置详解

Playwright MCP 完全指南：让 LLM 通过无障碍快照操作浏览器——安装、工具集与配置详解

2026-09-06 12:45:43作者：尤峻淳Whitney
playwright
Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
项目地址：https://gitcode.com/GitHub_Trending/pl/playwright

Playwright MCP 服务器通过 Model Context Protocol（MCP）把 Playwright 的浏览器自动化能力暴露给 LLM，使其无需视觉模型、仅凭结构化的无障碍快照（accessibility snapshot）即可导航、点击、填表和断言网页。读完本文，你将掌握在 VS Code、Cursor、Claude Code 等客户端中的完整安装方式、无障碍快照的工作原理、browser_run_code_unsafe 等核心工具的用法，以及 headed/headless、浏览器选择、用户配置文件（profile）、JSON 配置文件与独立 HTTP 服务器等全部配置项，并能结合源码理解其底层实现。

前置条件

开始前请确保环境满足以下要求：

  • Node.js 20 或更高版本；
  • 一个 MCP 客户端：VS Code、Cursor、Windsurf、Claude Code、Claude Desktop 或其他支持 MCP 的客户端。

安装：把 Playwright MCP 接入你的 MCP 客户端

所有客户端都使用同一份标准配置，通过 npx 拉起 MCP 服务器：

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

VS Code

可以通过 VS Code CLI 一键安装：

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

VS Code Insiders 使用相同的配置，将命令前缀换成对应的 insiders 安装入口即可。

Cursor

进入 Cursor Settings → MCP → Add new MCP Server，选择 command 类型，命令为 npx @playwright/mcp@latest。

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop 与其他客户端

Claude Desktop 按照 MCP 官方安装流程，把上文的标准 JSON 配置写入客户端的 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 提供的工具打开浏览器、导航到目标页面并操作元素——整个过程依赖的是结构化无障碍快照，而不是截图。

核心特性一：无障碍快照（Accessibility Snapshots）

Playwright MCP 操作的对象是页面的无障碍树（accessibility tree），而不是像素。每次工具调用都会返回一份结构化快照，展示页面元素的 role（角色）与文本内容，LLM 再利用快照中的元素引用（ref）进行交互：

- 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 勾选复选框。这套机制正是"无需视觉模型"的原因：文本化的快照比像素截图更省 token、更稳定、更利于 LLM 解析。

从源码结构看，快照行为可以通过配置调整：--snapshot-mode 决定响应中是否附带完整快照（full/none），--snapshot-boxes 会在快照中为每个元素附加视口相对坐标 [box=x,y,width,height]（对应 config.d.ts 中 snapshot.mode 与 snapshot.boxes 字段）。

核心特性二：页面交互工具集

Playwright MCP 覆盖了浏览器交互的全部常见场景：

  • 导航（Navigation）：打开 URL、前进/后退、刷新页面；
  • 点击与输入（Clicking and typing）：点击元素、输入文本、填写表单、选择下拉选项；
  • 截图（Screenshots）：截取当前页面或特定元素，用于视觉验证；
  • 键盘与鼠标：按键、悬停、拖放；
  • 对话框（Dialogs）：接受或取消浏览器原生对话框；
  • 标签页（Tabs）：创建、关闭、切换浏览器标签页。

工具在仓库中的实现位于 packages/playwright-core/src/tools/backend/ 目录，每个工具通过统一的 ToolSchema 注册：schema 定义了名称、描述与 zod 输入结构，并带有 type 标记（input/action/assertion/readOnly）。在 tool.ts 中，toMcpTool 会把这些标记翻译成 MCP 标准的注解（readOnlyHint、destructiveHint、openWorldHint），让客户端可以区分"只读工具"与"会改变浏览器状态的工具"。

核心特性三：运行 Playwright 代码（browser_run_code_unsafe）

对于超出单次工具调用范围的复杂交互，可以使用 browser_run_code_unsafe 工具直接执行 Playwright 脚本。该工具会在 Playwright 服务器进程中执行任意 JavaScript，等同于 RCE（远程代码执行），只应对可信的 MCP 客户端启用：

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

在源码层面（见 runCode.ts），该工具接受 code（一段以 page 为参数的 JS 函数）或 filename（从工作区读取的脚本文件）两种输入，实现上使用 Node 的 vm 模块创建隔离上下文，将函数编译后以 await __fn__(page) 的形式执行，并将返回值 JSON.stringify 后回传给客户端；同时通过 onUnhandledRejection 监听处理路由回调异步抛错的场景，避免无谓等待超时。相关行为由 tests/mcp/run-code.spec.ts 和 tests/mcp/cli-run-code.spec.ts 覆盖验证。

核心特性四：网络监控与模拟

  • 查看网络请求：列出页面加载以来发出的全部请求；
  • 模拟路由（Mock routes）：按 URL 模式匹配并返回自定义响应；
  • 控制台消息：读取浏览器 console 输出用于调试，--console-level 控制返回的级别（error/warning/info/debug，默认 info，见 config.d.ts 中 console.level）。

网络边界方面，network.allowedOrigins / network.blockedOrigins 支持完整 origin（如 https://example.com:8080）与通配端口（如 http://localhost:*）两种格式，blocklist 优先于 allowlist 生效；但源码注释明确说明，这些选项不构成安全边界、也不影响重定向（见 config.d.ts）。

核心特性五：存储状态（Storage State）

  • 保存状态：把认证与会话数据（cookies、localStorage）持久化到文件；
  • 恢复状态：将先前保存的状态加载进新会话；
  • Cookie 管理：列出、读取、设置、删除单个 cookie。

隔离会话下可用 --storage-state <path> 指定初始状态文件（对应 browser.isolated 配置），cookie 相关的测试见 tests/mcp/cookies.spec.ts 与 tests/mcp/storage.spec.ts。

配置详解

完整的命令行选项定义在 program.ts 的 decorateMCPCommand 中，JSON 配置结构定义在 config.d.ts，解析逻辑在 config.ts。以下逐一展开文档中最常用的几类配置。

有头/无头模式（Headed / Headless）

Playwright MCP 默认以有头（headed）模式运行浏览器，方便你观察操作过程。若希望后台运行，在 args 中加入 --headless：

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

浏览器选择

通过 --browser 指定浏览器，支持取值：chrome、firefox、webkit、msedge：

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

三种用户配置文件（Profile）模式

  • 持久模式（Persistent，默认）：登录态与 cookie 在会话之间保留。配置文件存储在平台缓存目录下的 ms-playwright/mcp-{channel}-{workspace-hash}，不同项目会自动获得独立 profile。可用 --user-data-dir 覆盖路径。
  • 隔离模式（Isolated）：每次会话都是全新状态，传入 --isolated 启用；可配合 --storage-state 加载初始状态。
  • 浏览器扩展模式（Extension）：连接你正在使用的浏览器标签页，需先安装 Playwright Extension，然后传入 --extension（仅 Edge/Chrome 可用）。

JSON 配置文件

进阶配置可以放在一个 JSON 文件中，通过 --config 加载：

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

配置文件支持浏览器选项（browser.browserName、launchOptions、contextOptions、CDP 连接等）、服务器选项（server.port、server.host、server.allowedHosts）、工具能力集（capabilities，如 core、pdf、vision、devtools、network、storage 等，见 config.d.ts 中的 ToolCapability 定义）、网络规则（network.allowedOrigins/blockedOrigins）、超时（timeouts.action 默认 5000ms、timeouts.navigation 默认 60000ms、timeouts.settle 默认 500ms）、secrets（把工具响应中的敏感明文替换掉，防止 LLM 意外获取，注释强调这是便利性措施而非安全特性）、outputDir/outputMaxSize（自动命名输出文件与清理阈值）等。完整 schema 以仓库中的 config.d.ts 为准。

独立服务器（HTTP 传输）

在无显示器的系统上运行有头浏览器、或从 IDE 工作进程调用时，可以让 MCP 服务器以 HTTP 传输独立启动：

npx @playwright/mcp@latest --port 8931

HTTP 会话带有 5 秒的心跳超时（heartbeat）。如果你的 MCP 客户端或代理不响应服务器发起的 ping，可以设置环境变量 PLAYWRIGHT_MCP_PING_TIMEOUT_MS 为更长的毫秒值；设为 0 则完全禁用心跳。这一逻辑在 server.ts 中实现：pingTimeout 读取该环境变量（默认 5000），startHeartbeat 每 3 秒 ping 一次，超时未响应即关闭连接。

启动后把 MCP 客户端指向 HTTP 端点：

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

从源码看（http.ts），服务器同时提供两种传输：标准的 Streamable HTTP 端点 /mcp，以及兼容旧客户端的 SSE 端点 /sse；服务器启动时会在 stderr 直接打印这段客户端配置供复制，并默认绑定 localhost、通过 Host 头校验防止 DNS 重绑定攻击（可用 --allowed-hosts 调整，传 * 关闭校验）。

快速参考表

操作 做法
安装服务器 向 MCP 客户端添加标准配置
导航到页面 问："Go to https://example.com"
点击元素 问："Click the Submit button"
填写表单 问："Fill in the email field with test@example.com"
截图 问："Take a screenshot of the page"
运行 Playwright 代码 问："Run this Playwright code: ..."
模拟 API 问："Mock the /api/users endpoint to return ..."
使用有头模式 默认行为；传 --headless 关闭
选择浏览器 在 args 中传 --browser=firefox

测试与延伸阅读

MCP 功能有庞大的测试套件支撑，位于 tests/mcp/ 目录，涵盖导航、点击、表单、网络拦截（route.spec.ts、request-blocking.spec.ts）、存储（storage.spec.ts、webstorage.spec.ts）、标签页（tabs.spec.ts）、截图（screenshot.spec.ts）、代码执行（run-code.spec.ts）、HTTP/SSE 传输（http.spec.ts、sse.spec.ts）等，可作为每个特性的可运行参照。

继续深入 Playwright 的后续学习路径：

playwright
Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
项目地址：https://gitcode.com/GitHub_Trending/pl/playwright
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.73 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
589
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
907
1.83 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.56 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
994
510
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
docsdocs
暂无描述
Markdown
894
5.79 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313