Playwright MCP Server已精选

什么是 Playwright MCP Server？

Playwright MCP Server 是 Microsoft 官方的 playwright mcp 软件包（@playwright/mcp），通过 Playwright 为 AI 智能体提供浏览器自动化能力。它让 LLM 通过结构化的无障碍快照（accessibility snapshot）而不是截图来读取和操作网页，因此无需视觉模型。

该项目基于 Apache-2.0 许可证开源，维护于 microsoft/playwright-mcp 仓库。默认通过 stdio 在本地运行，也可以作为独立的 HTTP 服务器启动，供 MCP 客户端通过 URL 连接。

如何使用 Playwright MCP Server？

前提条件：Node.js 18 或更高版本，以及一个 MCP 客户端，例如 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Codex 或 Goose。无需 API 密钥或账号。

标准配置适用于大多数客户端：

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

额外选项添加到 args 列表中，例如 "--headless"、"--browser=firefox" 或 "--isolated"。

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

按照 MCP 安装指南操作，将上面的标准配置粘贴到 Claude Desktop 配置文件中。

Cursor

进入 Cursor Settings -> MCP -> Add new MCP Server，选择 command 类型并输入 npx @playwright/mcp@latest。README 中也提供了一键安装按钮。

VS Code

在 VS Code 的 MCP 设置中使用标准配置，或通过命令行安装：

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

安装后，该服务器即可供 VS Code 中的 GitHub Copilot agent 使用。

Codex

codex mcp add playwright npx "@playwright/mcp@latest"

或添加到 ~/.codex/config.toml：

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Windsurf

按照 Windsurf MCP 文档操作，使用上面的标准配置。

独立 HTTP 服务器与 Docker

如需将 playwright mcp server 作为常驻进程运行（例如 IDE 无法打开有界面浏览器的机器上），可指定端口启动：

npx @playwright/mcp@latest --port 8931

然后让客户端指向该端点：

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

官方还发布了 Docker 镜像（mcr.microsoft.com/playwright/mcp），目前仅支持无头（headless）Chromium。

Playwright MCP Server 的主要功能

• 基于无障碍树：智能体基于结构化页面快照而非像素进行操作，动作快速且确定。
• 无需视觉模型：任何文本 LLM 都能驱动浏览器；截图功能可用但非必需。
• 多浏览器支持：--browser 可选 chrome、firefox、webkit 或 msedge，--device 或 --mobile 可模拟移动设备。
• 灵活的配置文件模式：默认使用持久化配置文件（登录状态在会话间保留），也可用 --isolated 开启内存隔离会话并配合 --storage-state，或通过 Playwright 浏览器扩展复用正在运行的 Chrome 或 Edge 标签页。
• 按需启用的能力：PDF 导出、基于坐标的鼠标控制、DevTools 追踪与录像、存储、网络路由和测试断言等额外工具组通过 --caps 启用。
• 细粒度配置：每个命令行参数都有对应的 PLAYWRIGHT_MCP_* 环境变量，也可通过 --config 加载 JSON 配置文件。
• 网络控制：代理设置、--allowed-origins 和 --blocked-origins 列表，以及用于 HTTP 服务器的 --allowed-hosts。

Playwright MCP Server 工具

默认工具集涵盖核心自动化：

• 导航与页面：browser_navigate、browser_navigate_back、browser_resize、browser_close，以及用于列出、打开、关闭和切换标签页的 browser_tabs。
• 读取页面：browser_snapshot 捕获智能体用来定位元素的无障碍快照；browser_find 在快照中搜索文本或正则表达式，比完整快照更省资源。browser_take_screenshot 保存图片，但不能用来选择操作目标。
• 交互：browser_click、browser_type、browser_fill_form、browser_select_option、browser_hover、browser_drag、browser_press_key、browser_file_upload、browser_drop 和 browser_handle_dialog。
• 调试：browser_console_messages、browser_network_requests 和查看请求头与正文的 browser_network_request，以及执行 JavaScript 的 browser_evaluate 和等待文本或超时的 browser_wait_for。
• 代码执行：browser_run_code_unsafe 在服务器进程中运行 Playwright 代码片段；README 将其标注为等同于 RCE（远程代码执行）。

可选工具组会增加 browser_pdf_save（--caps=pdf）、browser_mouse_click_xy（--caps=vision）、browser_start_tracing（--caps=devtools）、browser_cookie_list（--caps=storage）、browser_route（--caps=network）和 browser_verify_text_visible（--caps=testing）等工具。

Playwright MCP Server 的使用场景

• 探索性测试：“打开 localhost:3000，用测试账号注册，告诉我哪一步失败了。”
• 编写端到端测试：让智能体走完一个流程，再生成 Playwright 代码（--codegen 选项可设为 TypeScript、Python、Java 或 C#）。
• 自愈测试：让智能体检查当前页面结构，修复失败测试中失效的选择器。
• 调试前端问题：“加载结账页面，列出所有控制台错误和失败的网络请求。”
• 表单填写与数据录入：在没有 API 的 Web 应用中，借助持久化或通过扩展连接的已登录会话完成操作。
• 长时间运行的智能体工作流：需要在多个步骤之间保持浏览器状态。

Playwright MCP Server 与替代方案对比

• Playwright CLI + Skills：Microsoft 的 README 推荐编码智能体使用 Playwright CLI，因为 CLI 调用更节省 token。MCP 服务器更适合需要持久状态和丰富页面内省的智能体循环。
• Puppeteer MCP Server：基于 Puppeteer 的浏览器服务器；Playwright MCP 额外提供多浏览器支持和基于无障碍快照的元素定位。
• Browser Tools MCP：侧重通过扩展读取你自己 Chrome 中的日志和审计结果，而不是端到端驱动浏览器。

Playwright MCP Server 常见问题排查

• 无法从 IDE 打开有界面浏览器：在没有显示器的系统上，或 IDE 在工作进程中运行服务器时，请在有显示环境的终端中用 --port 8931 自行启动服务器，并通过 url 连接。
• 多个客户端同时运行时发生冲突：持久化配置文件同一时间只能被一个浏览器实例使用。为其他客户端使用 --isolated 或不同的 --user-data-dir。
• 缺少预期的工具：PDF、vision、DevTools、存储、网络和测试工具默认关闭；用 --caps 启用，例如 --caps=pdf。
• 无法读取本地文件或 file:// URL：文件访问默认限制在工作区根目录内。--allow-unrestricted-file-access 可解除此限制，请谨慎使用。
• Docker 中运行有界面浏览器失败：Docker 镜像仅支持无头 Chromium。