Playwright MCP for Operit

为 Operit 装上真正的浏览器。

让你的 AI 助手自己打开网页、阅读内容、搜索填表、截图取证——一切自动化，全程可观测。

本项目将微软官方的 Playwright MCP（v0.0.84）接入 Operit（Android 上的 AI 助手）。基于 Chromium 内核，在手机上获得与桌面浏览器一致的渲染与交互能力。

目录

• 版本更新记录（CHANGELOG）
• 环境要求
• 它能做什么
• 效果演示
• 快速开始
• 首次启动会发生什么
• 使用示例
• 常见问题
• 文档导航
• 相关链接
• License

环境要求

它能做什么

25 个 browser_* 工具，覆盖「打开 → 操作 → 取证」完整链路，工具面与官方 Playwright MCP v0.0.84 完全一致。

v1.0.6 起新增 browser_emulate_media（模拟媒体类型/打印/深浅色）；另有 browser_run_code_unsafe（执行任意代码）——该工具能力极强，仅在确认页面可信时使用。
v1.0.9 起 browser_tabs 支持 isolatedContext（多账号会话隔离）、browser_find 支持 maxResults（限制返回条数）、browser_network_requests 支持 all（跨导航保留请求记录）。

效果演示

下图是在真实设备（Android + proot arm64）上，由 AI 自动完成「打开网页 → 等待渲染 → 截图」的百度首页：

快速开始

方式零：从 Operit 市场安装（条目审核中，暂可能搜不到）

在 Operit 内打开插件市场 → 搜索 Playwright MCP → 安装 → 重启 MCP 服务即可。

⚠️ 市场条目目前仍在审核，可能搜索不到。搜不到请直接使用下面的「方式一」，两者安装结果完全一致。

插件采用自举设计：包内只带声明文件（package.json / requirements.txt / 转发器），依赖与 Chromium 在首次启动时由转发器自动补齐，因此市场包很小、也能做到装完即用。

方式一：一键脚本（最推荐）

A. 从 Release 下载完整包（国内推荐，无需访问 raw.githubusercontent.com）

1. 打开 Releases，下载 playwright-mcp-for-operit-v1.0.9.zip
2. 解压后进入目录执行：

unzip playwright-mcp-for-operit-v1.0.9.zip
cd playwright-mcp-for-operit-v1.0.9
bash install.sh            # 自动完成：环境检查 → 依赖安装 → Chromium 探测 → 配置生成 → 双路径部署 → venv

B. 只下载 install.sh（需要能访问 raw.githubusercontent.com）

curl -sL https://raw.githubusercontent.com/x15907982411/playwright-mcp-for-operit/main/install.sh -o install.sh
bash install.sh

💡 B 方案单独下载脚本时，脚本会自动从 GitHub API 补齐 scripts/playwrightmcp.py；
若本机连 api.github.com 也访问不了，请改用 A 方案（完整包无需联网拉任何脚本）。

可选参数：

bash install.sh --global       # 依赖装到全局 node_modules
bash install.sh --skip-deps    # 跳过依赖安装，交给自举转发器首次启动时处理
bash install.sh --keep-deps    # 重跑时保留已有 node_modules（不重装依赖）
bash install.sh --dry-run      # 只检查、不写文件
bash install.sh --help         # 显示完整帮助

完成后在 Operit 中重启 MCP 服务，ping_mcp(playwrightmcp) 能看到 25 个 browser_* 工具即可使用。

💡 脚本先保存到本地再执行（非 curl | bash 管道），建议运行前先 cat install.sh 浏览一遍。

💡 推荐在 proot 环境执行：Termux 与 proot 的 ~/.cache 不互通，双环境切换会重复下载 Chromium。

⚠️ npm 源提示：@playwright/[email protected] 依赖的 [email protected]* 为 alpha 版本，
国内镜像 registry.npmmirror.com 可能尚未同步；若 npm install 报 ETARGET，请用官方源：
npm install --registry https://registry.npmjs.org

🗑 卸载：bash uninstall.sh（支持 --keep-files / --purge / --dry-run）。

方式二：手动部署（概览）

需要自行控制每一步时，按以下顺序操作：

1. 准备插件目录（playwrightmcp.py 转发器 + requirements.txt + package.json + mcp.config.json）
2. 安装 Node 依赖：npm install（在 Linux 运行目录内，读 package.json）——也可跳过，交给首次启动自举
3. 写入 mcp_config.json（使用仓库全字段模板，勿手写精简片段）
4. 双路径部署（Android 源目录 + Linux 运行目录 ~/mcp_plugins/）+ 准备 venv
5. 重启 MCP 并验证（ping_mcp → 25 个工具）

📖 每步的完整命令、配置注释与回滚方式，见 docs/DEPLOY.md。

首次启动会发生什么

无论用哪种方式安装，首次启动 MCP 时转发器都会自动兜底：

1. 找不到 @playwright/mcp → 自动 npm install（插件目录本地优先，回退全局）；
2. 找不到 Chromium → 先复用本机已有的（~/.cache/ms-playwright），实在没有才下载（约 150MB，数分钟）；
3. 全程日志写在 ~/mcp_plugins/playwrightmcp/bootstrap.log。

💡 若首次启动因下载超时失败，再重启一次 MCP 即可（包与浏览器已就位）。

💡 可用 PW_MCP_AUTO_INSTALL=0 / PW_MCP_AUTO_DOWNLOAD=0 关闭自动行为（在 mcpServers.playwrightmcp.env 里设）。
💡 本机存在多个 chromium build 时，可用 PW_MCP_PREFERRED_BUILD（默认 1237）指定优先版本；详见 TROUBLESHOOTING 问题 13。

使用示例

激活后，AI 可以像这样完成一个完整任务：

use_package playwrightmcp

browser_navigate("https://www.baidu.com")     // 打开百度
browser_snapshot()                            // 读取页面结构
browser_type(target: "e36", text: "Operit")   // 搜索框输入
browser_click(target: "e63")                  // 点击「百度一下」
browser_take_screenshot()                     // 截图留证

整个过程是 打开 → 理解 → 操作 → 验证 的闭环，每一步都有结构化反馈（页面标题、无障碍树、网络日志），AI 可据此自主判断、纠错、继续。

常见问题

更多问题（apt 404、Chromium 镜像缺失、依赖库、截图落盘位置等）见 docs/TROUBLESHOOTING.md。

文档导航

相关链接

• 上游 MCP server：microsoft/playwright-mcp（v0.0.84，Apache-2.0）
• 运行平台：AAswordman/Operit
• 浏览器内核：Chromium（arm64 headless）

License

• 本项目（部署脚本 / 配置模板 / 文档）：MIT，详见 LICENSE
• 上游 MCP server：Microsoft Playwright MCP 为 Apache-2.0，安装时通过 npm 获取（@playwright/[email protected]），版权归 Microsoft 所有。本仓库不包含上游源代码
• 商标：Playwright 是 Microsoft 的商标。本项目为独立社区适配项目，与 Microsoft 无隶属关系；项目名中引用「Playwright」仅用于描述兼容性