你想让 AI 助手（Claude Code/Cursor/Codex 等支持 MCP 的 agent）真正操作浏览器：打开页面、点击、填表、抓取内容、跑测试——而不是只会给建议。playwright-mcp 就是官方出的 MCP server：把 Playwright 的浏览器能力包装成 MCP 工具，agent 通过标准 MCP 协议调用，就能真实驱动 Chromium。

什么时候用：

• 你的 agent 需要浏览器操作（填表/发帖/跨页面任务）；
• 你要用 AI 做网页自动化测试/抓取；
• 组合包 combo-auto-test（deepcode + swe-rex + playwright-mcp）的浏览器执行层。

什么时候别用：只需要人类手动浏览器测试（直接用 Playwright 脚本）；只需要 curl 抓页面（不需要浏览器渲染）。

国内网络的关键：npm 包本身走 npmmirror 镜像没问题；首次启动会下载浏览器引擎（chromium ~114MiB）。新版（server 1.63 系列）引擎改用 chrome-for-testing 布局，npmmirror 暂无该布局（实测 404），官方 CDN 实测 1 分钟可下完（2026-09-01 实测，见第 5 节）。

# 来源: Trove 详细指南 · 验证于 2026-08-29
npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install @playwright/mcp --port 8931 --headless

预期输出: Listening on http://localhost:8931（客户端配置 url 指向 /mcp 端点；2026-08-29 实测）

前置条件：Node ≥ 18（本环境 Node 24.15.0 实测）。首次启动自动下载 chromium（~114MiB）；下载慢时用 PLAYWRIGHT_DOWNLOAD_HOST（见第 5 节）。

装好确认：

• server 监听 8931；
• curl /mcp 返回非 200（拒绝非法 GET 属预期安全行为）；
• 无头浏览器冒烟能打开页面（见第 5 节操作三）。

npm 全局装 @playwright/mcp + 首次下载浏览器引擎（chromium 113.9MiB）；npx --no-install @playwright/mcp --port 8931 --headless 启动 MCP server（HTTP+SSE），客户端把 endpoint 配进 MCP 配置即可用。免安装形态 npx -y @playwright/mcp@latest 官方支持。

关键概念：

• MCP server：浏览器控制服务（HTTP+SSE，默认 8931）；
• --headless：无头模式（服务器环境可用）；
• workspace roots / allowed-hosts：默认安全边界。

装完它动哪里：不写项目/用户配置；浏览器引擎缓存落 ~/.cache/ms-playwright；运行时浏览器 profile 默认临时目录，不持久化。

第 1 步：启动 MCP server（HTTP+SSE 模式）

# 来源: Trove 详细指南 · 验证于 2026-08-29
npx --no-install @playwright/mcp --port 8931 --headless

预期输出: Listening on http://localhost:8931（客户端配置 url 指向 /mcp 端点；2026-08-29 实测）

卡住怎么办：

• npx 报找不到 → 全局装过但 npx --no-install 找不到，检查 npm 全局 bin 在 PATH；
• 端口被占 → --port 换端口；
• 报 Chromium distribution chrome is not found → 默认用 chrome 频道；自带引擎用 --browser chromium（2026-09-01 实测）；
• 报 file: protocol is blocked → 默认禁止 file:// 导航（安全边界），用 http:// 或加 --allow-unrestricted-file-access。

第 2 步：验证 server 存活

# 来源: Trove 详细指南 · 验证于 2026-08-29
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8931/mcp

预期输出: 非 200（拒绝非法 GET 属预期安全行为；POST JSON-RPC 才受理——2026-08-29 实测根路径 403）

卡住怎么办：

• 000/连接拒绝 → server 没起来，看第 1 步；
• 200 → 异常（MCP endpoint 对 GET 应拒绝），检查是否被其他服务占用 8931。

第 3 步：无头浏览器冒烟（自测浏览器引擎可用）

# 来源: Trove 详细指南 · 验证于 2026-08-29
node -e "const {chromium}=require('@playwright/mcp/node_modules/playwright');(async=>{const b=await chromium.launch({headless:true});const p=await b.newPage;await p.goto('data:text/html,<title>ok</title>');console.log(await p.title);await b.close})"

预期输出: ok（2026-08-29 实测通过）

卡住怎么办：

• 报浏览器未安装 → 首次启动没成功下载引擎；手动 npx playwright install chromium 或配 PLAYWRIGHT_DOWNLOAD_HOST 重装；
• 下载慢/失败 → 官方 CDN 实测可用：npx @playwright/mcp install-browser chrome-for-testing（114MiB 约 1 分钟，2026-09-01 实测）；注意 npmmirror 对新版 cft 布局暂无镜像（实测 404，经典 chromium 布局可用）。

第 4 步：接客户端

讲解：在支持 MCP 的客户端里配 endpoint（示例 Claude Code 的 mcp 配置）。

# 来源: Trove 详细指南 · 验证于 2026-08-29
# 示例（客户端配置，非命令）：url=http://localhost:8931/mcp, transport=http

预期输出: 客户端 MCP 工具列表出现 playwright 相关工具（browser_navigate/click/fill_form 等；2026-08-29 实测连接成功，2026-09-01 协议级复测：initialize 握手 + tools/list 枚举 20+ 工具，证据见第 10 节）

卡住怎么办：

• 客户端连不上 → 确认 server 在跑、url 用 /mcp 端点（不是根路径）；
• 报 Access is only allowed at localhost:8931 → server 校验 Host 头必须为 localhost，url 别写 127.0.0.1（2026-09-01 实测）；
• 工具不出现 → 重启客户端 MCP 连接。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• deepcode/swe-rex × playwright-mcp：组合包 combo-auto-test 成员（自动化测试执行层），互补；
• browser-use（未收录）：同为浏览器自动化定位相邻——browser-use 需求信号中等重叠（E2 轮判定暂不立项）；
• 其余：写面不重叠（~/.cache/ms-playwright + 临时 profile），静态判定可共存。

• 症状：启动报浏览器未安装 → 首次引擎下载失败；npx playwright install chromium 或配 PLAYWRIGHT_DOWNLOAD_HOST 重装
• 症状：curl /mcp 返回 403 → 正常（拒绝非法 GET）；POST JSON-RPC 才受理
• 症状：客户端连不上 → 确认 server 在跑、url 用 /mcp 端点（Host 必须 localhost，127.0.0.1 报 Access is only allowed at localhost:8931，实测）
• 症状：npx 找不到包 → 全局 bin 不在 PATH
• 症状：引擎下载慢 → PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright（国内镜像）

四段式全文（症状→原因→解法→验证证据）：站内文档（如已收录）

# 来源: Trove 详细指南 · 验证于 2026-08-29
npm uninstall -g @playwright/mcp --no-audit --no-fund && rm -rf ~/.cache/ms-playwright

预期输出: npm 移除输出（Removed N packages）；~/.cache/ms-playwright 不存在即为清理干净

注意：引擎缓存 ~114MiB，删除前确认没有其他 Playwright 项目在用同一缓存。

• 问：curl /mcp 返回 403 是坏了吗？答：不是。MCP endpoint 只受理 POST JSON-RPC，拒绝 GET 属预期安全行为（实测）。
• 问：浏览器引擎下载慢怎么办？答：PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright 指到国内镜像再装。
• 问：无头模式能用吗？答：能，--headless 实测通过（服务器环境可用）。
• 问：和 browser-use 重复吗？答：定位相邻但 playwright-mcp 是官方 MCP server、已收录；browser-use 需求信号中等重叠暂不立项（E2 判定）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：1.x（manifest 记录范围；实测 2026-08-29）。
• 环境：Node ≥18（24.15.0 实测）；浏览器引擎缓存 ~/.cache/ms-playwright（~114MiB）。
• 网络：npm 走 npmmirror；引擎下载可配 PLAYWRIGHT_DOWNLOAD_HOST 国内镜像。
• 写面：~/.cache/ms-playwright + 临时 profile；不写项目/用户配置。
• 端口：8931（默认）。

• 条目签名：microsoft/playwright-mcp（官方 MCP server，原样收录）

• 实测：`站内文档（2026-08-29：npm 安装 + 引擎下载 + MCP server 启动 Listening + curl /mcp 403 安全行为 + 无头浏览器冒烟 ok；2026-08-30 usage 实测补强）
• 未实测：真实业务站点的复杂交互自动化（本次为本地测试页全链路）；免安装 npx 形态；Windows/macOS 形态。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方 README（npm registry readme 字段，v0.0.79）：Playwright MCP 完整用法 [官方文档 · Playwright 官方 · 2026-08-31（包 0.0.79）]
  官方用法全解——MCP 服务器接入（Claude/其他客户端）、启动方式（CLI / npx / 独立服务器）、配置（浏览器/能力开关 vision/pdf/devtools、用户目录、启动页）、跨平台（Windows/macOS/Linux）、VS Code 集成、standalone server 形态、与 Playwright CLI 的边界