CloakBrowser MCP

cloakbrowser-mcp

cloakbrowser-mcp 是一个可直接替换、兼容 Playwright MCP 的浏览器自动化服务，使用未经修改的上游工具、CloakBrowser Chromium，并提供适用于生产环境的 npm、Docker 和 Streamable HTTP 打包方案。它将上游 @playwright/mcp 作为标准工具接口运行，并让该运行时使用 CloakBrowser。

30 秒演示

运行 npx -y cloakbrowser-mcp@latest，连接 Claude Desktop 或 Codex CLI，用日常语言提出网页研究、日常自动化或测试需求，然后检查浏览器中的实际结果。

文档：swimmwatch.github.io/cloakbrowser-mcp · 对比 · 操作指南

适用于以下需求：

• 由 CloakBrowser 驱动的 Playwright MCP 浏览器自动化；
• 未经修改的上游浏览器工具，以及两个本地自省工具；
• 通过 stdio 或 Streamable HTTP 使用 npm 或 Docker 安装；
• 为支持 CDP 的客户端提供可选的、按会话作用域管理的 CDP 访问， 通过 chromium.connectOverCDP() 实现；
• 持久化浏览器配置文件、经过验证的上下文选项和 Chrome 扩展加载；
• 用于区域化 QA 的 GeoIP 感知代理匹配；
• 用于交互敏感型流程的拟人化鼠标、键盘和滚动行为。

跨平台检查涵盖 Linux x64/arm64、macOS arm64/x64 和 Windows x64 上的 npm，支持的 Node.js 版本见测试。Docker 镜像会针对 linux/amd64 和 linux/arm64 构建并进行冒烟测试。

选择更适合部署的方案时，请参阅 @playwright/mcp 与 cloakbrowser-mcp 的对比，了解直接使用上游 Playwright MCP 或 CloakBrowser MCP。操作指南页面提供了面向具体任务的设置流程，涵盖持久化登录配置文件、Chrome 扩展、反向代理、区域化 QA、客户端连接和 CI 冒烟测试。

使用 npm 安装

npx -y cloakbrowser-mcp@latest

需要 Node.js 22.13+（22.x 系列）或 Node.js 24+。配置客户端前，请先运行诊断：

npx -y cloakbrowser-mcp@latest doctor

如需使用 Streamable HTTP 而非 stdio：

npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000

所有标志请参阅生成的 CLI 参考。

使用 Docker 安装

docker run --rm -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

使用 Streamable HTTP：

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

Docker 镜像会将产物写入 /data，并针对 linux/amd64 和 linux/arm64 发布。镜像默认将 CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX=true，以兼容容器化运行时，因为这类环境通常无法使用 Chromium 沙箱。如果宿主机和容器运行时支持 Chromium 沙箱，请设置 CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX=false；对于不受信任的页面，请严格限制容器的网络访问和挂载的宿主机目录。相同标签也可从 ghcr.io/swimmwatch/cloakbrowser-mcp 获取。持久化配置文件、扩展挂载、HTTPS 和冒烟测试示例，请参阅 Docker；如需专门了解 Streamable HTTP 部署，请使用反向代理操作指南。

添加到 MCP 客户端

Codex CLI

codex mcp add cloakbrowser -- npx -y cloakbrowser-mcp@latest

Claude Code

claude mcp add --transport stdio cloakbrowser -- npx -y cloakbrowser-mcp@latest

VS Code 中的 GitHub Copilot

{
  "servers": {
    "cloakbrowser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cloakbrowser-mcp@latest"]
    }
  }
}

Claude Desktop、Cursor、Cline、Windsurf、Warp 和其他 mcpServers 客户端

将此服务条目添加到客户端的 MCP JSON 配置中：

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "npx",
      "args": ["-y", "cloakbrowser-mcp@latest"]
    }
  }
}

基于 Docker 的 stdio

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

已运行的 Streamable HTTP 服务

npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000
codex mcp add cloakbrowser --url http://127.0.0.1:3000/mcp
claude mcp add --transport http cloakbrowser http://127.0.0.1:3000/mcp

面向编码助手的提示词

将以下内容粘贴到 Codex、Claude Code、Copilot、Cursor、Cline、Windsurf 或其他能够编辑 MCP 配置的类似编码助手中：

Install the CloakBrowser MCP server for this workspace. Name it "cloakbrowser".
Prefer stdio with command "npx" and args ["-y", "cloakbrowser-mcp@latest"].
If this client uses VS Code mcp.json, add it under "servers" with type "stdio".
If this client uses Claude/Cursor/Cline/Windsurf/Warp-style config, add it under
"mcpServers" with the same command and args. Do not add secrets.

更多示例请参阅快速入门，其中还为 Claude Desktop 和 Codex CLI 提供了专门的配置方案。

配置

浏览器、制品、超时、网络和工具功能设置请使用上游的 PLAYWRIGHT_MCP_* 变量。Cloak 专用的桥接开关使用 CLOAK_PLAYWRIGHT_MCP_*。启动前，可通过 --release-channel preview 或 CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL=preview 选择 Pro Preview 浏览器版本；默认值为 stable。

常用变量表现已移至配置。该页面还介绍了持久化配置文件、经过验证的上下文选项、Chrome 扩展、Streamable HTTP 元数据，以及 HTTPS/身份验证选项。有关区域代理行为，请参阅GeoIP 代理匹配；有关交互真实感，请参阅拟人化输入行为；有关面向任务的配置，请参阅配置方案。

版本兼容性

cloakbrowser-mcp	@playwright/mcp	CloakBrowser	Node.js	平台
1.15.1	^0.0.83	^0.6.3	`^22.13.0
1.15.0	^0.0.83	^0.6.3	`^22.13.0
1.14.1	^0.0.82	^0.5.10	`^22.13.0
1.14.0	^0.0.82	^0.5.10	`^22.13.0
1.13.0	^0.0.80	^0.5.10	`^22.13.0
1.12.0	^0.0.79	^0.5.7	`^22.13.0
1.11.0	^0.0.79	^0.5.6	`^22.13.0
1.10.0	^0.0.78	^0.5.3	`^22.13.0
1.9.0	^0.0.78	^0.5.1	`^22.13.0
1.8.0	^0.0.78	^0.4.10	`^22.13.0
1.7.0	^0.0.77	^0.4.8	>=22.12	Linux x64/arm64、macOS arm64/x64、Windows x64 上的 npm；Docker linux/amd64、linux/arm64
1.6.1	^0.0.77	^0.4.7	>=22.12	Linux x64/arm64、macOS arm64/x64、Windows x64 上的 npm；Docker linux/amd64、linux/arm64
1.6.0	^0.0.77	^0.4.7	>=22.12	Linux x64/arm64、macOS arm64/x64、Windows x64 上的 npm；Docker linux/amd64、linux/arm64
1.5.0	^0.0.76	^0.4.3	>=22.12	Linux x64/arm64、macOS arm64/x64、Windows x64 上的 npm；Docker linux/amd64、linux/arm64
1.4.0	^0.0.76	^0.3.32	>=22.12	Linux x64/arm64、macOS arm64/x64、Windows x64 上的 npm；Docker linux/amd64、linux/arm64
1.3.0	^0.0.75	^0.3.31	>=20	Docker linux/amd64、本地 Node.js
1.2.7	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.6	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.5	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.3	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.2	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.1	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.2.0	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.1.0	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.0.2	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.0.1	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
1.0.0	^0.0.75	^0.3.30	>=20	Docker linux/amd64、本地 Node.js
请参阅版本兼容性，了解维护中的兼容性表。

工具

上游 Playwright MCP 工具列表具有权威性。本项目不会在源代码中重新实现或重新说明上游浏览器架构。

本地工具：

• cloakbrowser_binary_info 返回 CloakBrowser 包、平台、缓存和已解析的二进制文件数据。
• cloakbrowser_bridge_info 返回桥接元数据、上游包/版本以及本地工具名称。

开发

npm install
npm run build
npm test
npm run docker:build
npm run docker:smoke
npm run server:validate
npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json

文档从docs/getting-started.md开始。贡献者资料归类在docs/contributor-guide.md下。

有关本地 Allure 报告和通过拉取请求链接的 CI 矩阵综合报告，请参阅测试报告。