playwright-mcp

你会遇到什么

这个工具解决什么问题：Agent 只能读代码，不能「看网页」。playwright-mcp 通过标准 MCP 协议给 Agent 一个浏览器控制面：navigate / click / fill / screenshot / assert——部署验证、E2E、截图都能干。 什么时候用：

• 你要让 Agent 验证网页部署（打开页面、断言内容、截图）；
• 你要浏览器 E2E（点按钮、填表单、看结果）；
• 你要在无 GUI 服务器上做浏览器自动化（--headless，实测可用）。

什么时候别用：纯接口测试（不需要浏览器渲染）时——headless 浏览器是重依赖。 注意事项：默认权限受限（文件访问限 workspace roots、导航限 allowed-hosts）；敏感开关（如 --allow-unrestricted-file-access）需显式开启。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：npm 全局装 @playwright/mcp + 首次下载浏览器引擎（chromium 113.9MiB）；npx --no-install @playwright/mcp --port 8931 --headless --browser chromium 启动 MCP server（HTTP+SSE；--browser chromium 用自带引擎，2026-09-01 实测新版本默认 chrome 频道会报错），客户端把 endpoint 配进 MCP 配置即可用。免安装形态 npx -y @playwright/mcp@latest 官方支持。 关键概念：

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

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

一步步来

第 1 步：装 npm 包 + 浏览器引擎（为什么两步：引擎 113.9MiB，首次必装）

讲解：npm 包本身秒装（2026-08-29 实测）；浏览器引擎 chromium 113.9MiB 需单独下载（首次必装）。国内 npm 用 npmmirror 前缀。

npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install @playwright/mcp --version

预期输出: Version 0.0.79

npx --no-install playwright install chromium

预期输出: 浏览器引擎下载完成（2026-08-29 实测下载成功）

装好确认：

• --version 输出 0.0.79；
• 引擎下载完成无报错。

卡住怎么办：

• npm 慢 → 确认带 npmmirror 前缀；
• 引擎下载失败 → 重试；确认磁盘空间（约 114MiB 缓存）；
• Node 版本 → 确认 >= 18。

第 2 步：启动 MCP server 并验证（本环境实测）

讲解：--port 8931 --headless 启动（无 GUI 服务器用 --headless）。客户端配置 url 指向 /mcp 端点；server 只受理 POST JSON-RPC，GET 返回非 200 属预期安全行为。

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

预期输出: Listening on http://localhost:8931（客户端配置 url 指向 /mcp 端点；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）

装好确认：

• 启动日志出现 Listening；
• curl 返回非 200（403 属预期）。

卡住怎么办：

• 端口被占 → 换 --port；
• 启动失败 → 确认引擎已装（第 1 步）。

第 3 步：无头浏览器冒烟（自测引擎可用，本环境实测）

讲解：直接用 playwright 库拉起 chromium headless 打开页面取标题，确认引擎可用——这条通过说明浏览器链路 OK，MCP 面问题不在这层。

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 实测通过）

卡住怎么办：

• require 路径找不到 → 确认引擎已装（第 1 步）且包路径未变；
• launch 失败 → 确认 --headless 模式与系统依赖（无头 shell 实测通过）。

怎么确认修好了

第 1 步：确认包与引擎就位

讲解：--version 输出 0.0.79 确认 npm 包；浏览器引擎是独立下载的（113.9MiB），引擎没装时启动会报错。

npx --no-install @playwright/mcp --version

预期输出: Version 0.0.79

卡住怎么办：

• 版本对不上 → 重新 npm install；
• 引擎缺失 → 跑 npx --no-install playwright install chromium。

第 2 步：启动 + 无头浏览器冒烟

讲解：server 能 Listening、无头浏览器能打开页面取到标题，说明 MCP 面与浏览器链路都通。

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

预期输出: Listening on http://localhost:8931（客户端配置 url 指向 /mcp 端点）

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 实测通过）

卡住怎么办：

• require 路径找不到 → 确认引擎已装且包路径未变；
• launch 失败 → 确认 --headless 模式与系统依赖。

其它环境的表现（常见变体）

• 有 GUI 的机器：可去掉 --headless 看真实浏览器操作（无头 shell 实测通过）。
• Windows / macOS：npm 安装与启动命令一致（国内仍建议 npmmirror 前缀）；引擎缓存路径在 ~/.cache/ms-playwright。
• 端口：默认 8931，--port 可改；被占时换一个即可。
• 安全：默认文件访问限 workspace roots、导航限 allowed-hosts；--allow-unrestricted-file-access 等敏感开关需显式开启。

日常使用

启动与入口

• MCP server：npx --no-install @playwright/mcp --port 8931 --headless --browser chromium；
• 客户端：endpoint 配 http://localhost:8931/mcp。

常用操作

操作一：启动 MCP server（HTTP+SSE 模式）

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

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

操作二：验证 server 存活

curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8931/mcp

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

操作三：无头浏览器冒烟（自测浏览器引擎可用）

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 实测通过）

数据与目录

• 浏览器引擎缓存：~/.cache/ms-playwright/（约 114MiB）；
• 运行时 profile：临时目录，不持久化。

卸载与清理

note: npm 全局卸载 + 命令面验证；浏览器引擎缓存 ~/.cache/ms-playwright 可选删除

npm uninstall -g @playwright/mcp
command -v @playwright/mcp >/dev/null 2>&1 && echo "残留: playwright-mcp 仍存在" || echo "playwright-mcp removed: OK"

预期输出: playwright-mcp removed: OK

手动确认清单（如需彻底清理）：

• ~/.cache/ms-playwright/（浏览器引擎缓存，约 114MiB，可删除对应版本目录）
• 运行中的 MCP server 进程（默认 8931 端口，lsof -i :8931 查看）

依赖警告

• 版本：[0.0.79, 0.0.79] 锁定（2026-08-29 实测版本）。
• 环境：Node >= 18；浏览器引擎 chromium 113.9MiB（首次必装，缓存 ~/.cache/ms-playwright）；无 GUI 用 --headless。
• 网络：npm 用 npmmirror 前缀（2026-08-29 实测秒装）。
• 端口：默认 8931（--port 可改）。
• 安全：默认文件访问限 workspace roots、导航限 allowed-hosts；--allow-unrestricted-file-access 等敏感开关需显式开启。
• 写面：无项目/用户配置写入；引擎缓存 + 临时 profile。
• 共装：与 vite-deploy 判定 possible-compatible（部署写构建产物、验证写浏览器，写面不重叠）；组合包「网页部署验证」见 站内文档。

FAQ（常见问题）

• 问：会改我的配置吗？答：不写项目/用户配置；浏览器引擎缓存落 ~/.cache/ms-playwright；运行时浏览器 profile 默认临时目录，不持久化。
• 问：安全边界？答：默认文件访问限 workspace roots、导航限 allowed-hosts；--allow-unrestricted-file-access 等敏感开关需显式开启（2026-08-29 帮助面确认）。
• 问：无 GUI 的服务器环境能用吗？答：能，--headless 无头模式（2026-08-29 实测 chromium headless shell 冒烟通过）。
• 问：和 vite-deploy 一起用？答：判定 possible-compatible——部署（构建产物）与验证（浏览器）写面不重叠，共装未实测；组合包「网页部署验证」见 站内文档。
• 问：国内 npm 装不上？答：用安装段的 npmmirror 前缀（2026-08-29 实测秒装）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。