microsoft/playwright-mcp · 上手攻略

仓库：microsoft/playwright-mcp
链接：https://github.com/microsoft/playwright-mcp
分类：skill（AI Agent · 浏览器自动化 · MCP）
作者：Jay
更新：2026-07-09

这是什么

Playwright MCP Server 是微软 Playwright 团队开源的 Model Context Protocol（MCP）服务器，让大语言模型（LLM）可以通过标准化的 MCP 协议驱动真实浏览器，完成网页交互、自动化测试、表单填写等任务。

它的核心特点：不需要视觉模型，基于 Playwright 的无障碍树（Accessibility Tree）进行页面导航——也就是说，AI 看到的是结构化的页面元素描述，而非像素截图。这让它在 token 消耗和执行速度上都有明显优势。

能解决什么问题

AI 编程 Agent 需要操作浏览器：当你让 AI 帮你填表单、截图验证网页行为、抓取动态渲染内容时，Playwright MCP 让这件事标准化了。
端到端测试自动化：用自然语言描述测试步骤，AI 通过 MCP 驱动真实浏览器执行。
多客户端兼容：同一套工具，同时支持 Claude Desktop、Cursor、VS Code（Copilot）、Claude Code、Goose 等主流 AI 编程工具。
降低 token 消耗：相比截图方案，访问树方式单次任务约消耗 27K tokens（CLI 模式）vs 114K tokens（MCP 模式），显著节省成本。

快速安装

前置要求

Node.js 18+（建议用 npx 方式运行）
MCP 客户端：Claude Desktop、Cursor、VS Code（Copilot）、Claude Code、Goose 等任意支持 MCP 的工具

标准配置（一键接入）

在对应客户端的 MCP 配置文件中添加以下内容：

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

各客户端的配置文件位置：

客户端	配置文件路径
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json` 或项目级 `.cursor/mcp.json`
VS Code（Copilot）	`~/.copilot/mcp-config.json`
Claude Code	`~/.claude/settings.json`
Goose	`~/.config/goose/mcp.json`（或 UI 内配置）
Cline	`~/.cline/cline_mcp_settings.json`

Claude Desktop（macOS）具体步骤

找到配置文件：~/Library/Application Support/Claude/
编辑 claude_desktop_config.json，在 mcpServers 节点添加上面那段配置
重启 Claude Desktop
在对话框中输入：Navigate to https://example.com and take a screenshot

Cursor 图形界面安装

访问：https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D

或在 Cursor → Settings → MCP → Add new MCP Server → Name 随意填，Command type 选 npx，Args 填 @playwright/mcp@latest。

VS Code Copilot 安装

# 终端一键安装
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

核心用法

基础交互（用自然语言驱动）

安装完成后，直接用自然语言让 AI 操作浏览器：

"Go to https://github.com and search for 'playwright'"
"Click the Sign In button"
"Fill the email field with test@example.com"
"Take a screenshot of the current page"

AI 会通过 MCP 工具与浏览器交互，全程不需要截图输入。

指定浏览器

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

支持：chrome（默认）、firefox、webkit、msedge。

无头模式（Headless）

默认是有头模式（可以看到浏览器窗口）。在服务器/CI 环境中：

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

独立 HTTP 服务器模式（远程 MCP 客户端接入）

npx @playwright/mcp@latest --port 8931

然后在 MCP 客户端使用：

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

进阶：自定义配置文件

Playwright MCP 支持 JSON 配置文件（支持浏览器选项、网络规则、超时设置等）：

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

完整配置 schema 参见：config.d.ts

MCP 提供的核心工具

基于 Playwright MCP 文档，主要工具包括：

工具类别	具体操作
导航	`navigate`（打开 URL）、`go_back`、`go_forward`、`reload`
交互	`click`、`type`、`fill`、`select_option`、`hover`、`drag`
页面内容	`screenshot`、`get_snapshot`（获取无障碍树）
对话框	`accept_dialog`、`dismiss_dialog`
标签页	`new_page`、`close_page`、`switch_page`
网络	`network_intercept`、`mock_response`
存储	`save_storage_state`、`load_storage_state`、`get_cookies`

⚠️ 注意：browser_run_code_unsafe 工具可以执行任意 JavaScript（RCE 级别能力），仅对可信 MCP 客户端开启。

典型适用场景

场景一：AI 编程 Agent 自动验证网页行为

例如，你让 AI 帮你修一个前端 Bug，AI 可以自己打开页面、点击按钮、验证修改效果，而不需要你手动操作浏览器。

场景二：自动填写长表单

把一串字段数据给 AI，AI 通过 MCP 自动填入表单并提交。适用于批量注册、数据录入等重复性操作。

场景三：动态网页内容抓取

传统爬虫无法处理 React/Vue 等 SPA 的动态渲染，MCP 可以让 AI 等页面加载完成后"看到"完整内容再提取。

场景四：端到端（E2E）测试编写

用自然语言描述测试流程，AI 自动生成 Playwright 脚本并执行验证，降低测试门槛。

坑与注意

Playwright 浏览器未安装：首次运行会提示安装浏览器（npx playwright install），这会下载数百 MB 的 Chromium/Firefox/WebKit，建议在 CI 中用 Docker 镜像方式预装。
token 消耗高于 CLI：评测数据显示 MCP 模式约 114K tokens/任务，而 Playwright CLI 模式仅 27K tokens——如果你用的是 Claude Code 这类注重 token 成本的工具，可能需要权衡选择。
无障碍树精度问题：某些现代化 Web 组件（Shadow DOM、自定义控件）的无障碍树描述可能不完整，AI 操作会失败，此时需要降级为截图方案。
--headless 在 macOS 有窗口管理器限制：macOS 上某些 GUI 操作在无头模式下行为可能与有头模式不同，建议开发调试阶段用有头模式。
配置文件中的敏感路径：--user-data-dir 默认使用系统缓存目录，多个项目共享时数据会串扰，建议显式指定项目级数据目录。
浏览器扩展模式：--extension 参数可以接管已有浏览器标签页的调试，但需要安装 Playwright 浏览器扩展，适用于已有登录态需要复用的场景。

与同类对比

工具	类型	接入方式	Token 消耗	适用场景
Playwright MCP	MCP Server	MCP 协议	~114K/任务	AI Agent 集成、编程工具
Playwright CLI	CLI	命令行+文件	~27K/任务	高吞吐量自动化、CI
Puppeteer MCP	MCP Server	MCP 协议	较高	特定 Chrome 定制场景
browser-use	Python Lib	直接调用	高	原生 Python Agent 集成
Selenium	WebDriver	传统协议	中	传统自动化测试

Playwright MCP 的核心优势是标准化 + 生态兼容——用 MCP 协议让 AI 工具和浏览器自动化解耦，而 Playwright CLI 更适合高吞吐量场景（如 CI）。两者可以互补。

一句话推荐结论

Playwright MCP 是目前 AI 编程工具生态中最成熟的浏览器自动化 MCP 方案——如果你在用 Claude Desktop、Cursor 或其他支持 MCP 的 IDE，5 分钟就能把浏览器自动化能力接进来，让 AI 真正"看到"并操作网页。