cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

MCP

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 和 Playwright 文档。大多数客户端可用这份标准配置:

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

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

在 Claude Code 中,于终端执行:

claude mcp add playwright npx @playwright/mcp@latest

在 VS Code 中,也可用官方 CLI:

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 和 issue #942 都报告过 Browser is already in use。
  • Windows 上找不到 Chrome。issue #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,不要把两套命令混用。

默认会打开可见窗口吗?

会。官方写明默认是有界面(headed),只有加了 --headless 才在后台运行。

为什么有的工具找不到?

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

可以同时开两个客户端吗?

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

来源与许可

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

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。