# Playwright MCP

Canonical: https://cqbase.net/zh/entry/playwright-mcp
Chinese: https://cqbase.net/zh/entry/playwright-mcp
English: https://cqbase.net/en/entry/playwright-mcp

> 微软的 Playwright MCP，让代理用浏览器自动化做页面操作。

microsoft/playwright-mcp 用 Apache-2.0 发布，npm 包是 @playwright/mcp。它让支持 MCP 的代理通过 Playwright 打开页面、点击和读取结果，适合需要复现一个界面流程的开发任务。

先用公开的测试页面或你自己的本地服务试通，再考虑登录态。登录态等于把会话交给代理，范围要写小。

## 解决什么问题

Playwright MCP 是微软的官方 MCP 服务器，让大模型通过 Playwright 操作浏览器。它主要依靠页面的无障碍（accessibility）快照来定位元素，官方介绍说不依赖视觉模型也能完成常见点击、输入和导航。

仓库 README 也提到，现在有些编码代理更倾向用 Playwright CLI 配合技能，因为命令行通常更省上下文；MCP 仍然适合需要保持浏览器状态、反复查看页面结构的探索式操作。两者不要混成同一个产品。本文只写 MCP。

## 适合谁

适合已经在用 VS Code、Cursor、Claude Code、Claude Desktop 或其他 MCP 客户端，并希望代理实际打开页面做操作的人。它本身是开源的，Apache-2.0 许可，官方入门配置不要求 API key。

Node 版本在官方材料里并不完全一致：仓库 README 写的是 Node.js 18 或更新；Playwright 文档站的 MCP 入门页写的是 Node.js 20 或更新。本文不擅自统一，请按你使用的文档来源安装，并在本机确认 `node -v`。

官方还提醒：Playwright MCP **不是**安全边界。代理能看到并操作它控制的页面，请不要对已登录、含敏感信息的会话随便授权。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai），命令来自 [仓库 README](https://github.com/microsoft/playwright-mcp) 和 [Playwright 文档](https://playwright.dev/docs/getting-started-mcp)。大多数客户端可用这份标准配置：

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

在 Cursor 中，打开 Cursor Settings → MCP → Add new MCP Server，类型选 command，命令填 `npx @playwright/mcp@latest`。

在 Claude Code 中，于终端执行：

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

在 VS Code 中，也可用官方 CLI：

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

默认启用的是核心工具，例如 `browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_take_screenshot`。网络模拟、存储、测试断言、视觉或 PDF 等额外能力要用 `--caps` 打开，例如 `--caps=vision,pdf,devtools`。浏览器默认是有界面的；无界面运行需加 `--headless`。同一套持久配置文件不能同时给多个实例用，并行时要加 `--isolated`，或指定不同的 `--user-data-dir`。

## 一个实际例子

下面的提示词是为本文写的验证步骤，不是官方固定口令。本次没有在本机实跑，因此不编造页面结构和截图。

1. 按上一节完成安装，并在客户端确认能看到 Playwright 工具。
2. 发送：`Open https://playwright.dev, take an accessibility snapshot, and tell me the main heading and the first few navigation links.`
3. 按官方工具说明，代理通常应先调用 `browser_navigate` 打开页面，再调用 `browser_snapshot` 读取无障碍树，而不是先去「看」一张图。核心工具里也有截图，但入门介绍强调的是快照。
4. 请自己核对标题和导航是否与你看到的页面一致。官方写过，快照返回的是无障碍树，不是完整 HTML。

## 常见坑

- 提示浏览器配置已被占用。官方说明：持久配置一次只能被一个浏览器实例使用。并行客户端应加 `--isolated` 或分开用户目录。[issue #769](https://github.com/microsoft/playwright-mcp/issues/769) 和 [issue #942](https://github.com/microsoft/playwright-mcp/issues/942) 都报告过 `Browser is already in use`。
- Windows 上找不到 Chrome。[issue #13](https://github.com/microsoft/playwright-mcp/issues/13) 报告过 `chrome' is not found`。先确认本机有可用浏览器，并按当前 README 安装或指定浏览器通道，不要沿用过时的第三方步骤。
- 把它当成隔离沙箱。README 的安全节写明它不是安全边界，并指向 MCP 的安全实践文档。对含登录态或密钥的页面要格外小心。
- Node 版本对不上。若启动失败，先核对你读的是 README 的 18+ 还是文档站的 20+，再检查本机 Node，不要自行「取平均」。

## FAQ

### 需要 API key 或付费账号吗？

官方入门配置不要求 Playwright 的 API key。你需要的是符合文档要求的 Node.js，以及一个 MCP 客户端。客户端本身（例如 Claude Code）可能另有自己的账号要求。

### MCP 和 Playwright CLI 怎么选？

README 把它们区分得很清楚：CLI 加技能通常更省 token；MCP 适合要保持浏览器状态、反复检查页面的场景。若你的代理已经主推 CLI，请另看 [playwright-cli](https://github.com/microsoft/playwright-cli)，不要把两套命令混用。

### 默认会打开可见窗口吗？

会。官方写明默认是有界面（headed），只有加了 `--headless` 才在后台运行。

### 为什么有的工具找不到？

默认只开核心工具。网络、存储、测试、vision、pdf、devtools 等要在启动参数里用 `--caps` 启用。不要假定所有工具一开始都在。

### 可以同时开两个客户端吗？

可以，但不要共享同一份持久配置。官方建议额外实例使用 `--isolated`，或给它们不同的 `--user-data-dir`。

## 来源与许可

仓库 [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) 使用 Apache-2.0 许可。本文依据 2026-11-15 查阅的 README 和 [Playwright MCP 入门文档](https://playwright.dev/docs/getting-started-mcp)，用自己的话写成，供 CQBase 上下文库使用。若安装命令或 Node 要求有变，以这两处官方材料为准。

## 收录信息

- 作者: microsoft
- 许可证: Apache-2.0
- 来源: https://github.com/microsoft/playwright-mcp
- 收录: 2026-11-15
- GitHub 星标: 39660（采集 2026-11-15）

