CloakMCP

CloakBrowser MCP

面向 AI Agent 的隐身浏览器自动化 — 一个模型上下文协议服务，将 CloakBrowser 的反检测功能与受 Playwright MCP 启发的架构相结合。

CloakBrowser 是经过源码级修补的 Chromium，可通过 Cloudflare Turnstile、reCAPTCHA v3（0.9 分）、FingerprintJS、BrowserScan 以及 30 多种机器人检测服务。

为什么选择 CloakBrowser MCP？

功能	Playwright MCP	CloakBrowser MCP
反检测	❌ 无	✅ 源码修补版 Chromium
绕过 Cloudflare	❌	✅
reCAPTCHA v3	❌	✅ 0.9 分
快照优先	✅	✅
Markdown 提取	❌	✅ 类 Readability
带注释的屏幕截图	❌	✅ browser-use 风格
智能页面稳定检测	基础	✅ MutationObserver + networkidle
点击自动重试	❌	✅
拟人化输入	❌	✅ 鼠标轨迹、键盘时序
能力门控	✅ --caps	✅ --caps

快速开始

安装

pip install cloakbrowsermcp

与 Claude Desktop 搭配使用

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "cloakbrowsermcp"
    }
  }
}

与 VS Code / Cursor 搭配使用

添加到 .vscode/mcp.json：

{
  "servers": {
    "cloakbrowser": {
      "command": "cloakbrowsermcp",
      "args": ["--caps", "all"]
    }
  }
}

与 Hermes Agent 搭配使用

添加到 ~/.hermes/config.yaml：

mcp_servers:
  cloakbrowser:
    command: cloakbrowsermcp
    args: ["--caps", "all"]
    timeout: 120

工作原理

快照优先架构

CloakBrowser MCP 使用无障碍树快照作为 AI 模型理解网页的主要方式——而不是屏幕截图，也不是原始 HTML。

1. cloak_launch()           → Start stealth browser
2. cloak_navigate(pid, url) → Go to page (auto-waits for settle)
3. cloak_snapshot(pid)      → Get interactive elements with [@eN] refs
4. cloak_click(pid, '@e5')  → Click element by ref
5. cloak_type(pid, '@e3', 'hello')  → Type into input
6. cloak_read_page(pid)     → Get content as clean markdown
7. cloak_close()            → Done

每个可交互元素都会获得一个 [@eN] 引用 ID。所有交互工具都使用这些引用——无需 CSS 选择器。

查看页面的三种方式

1. cloak_snapshot() — 带有 [@eN] 引用的无障碍树。快速、经济、可靠。请使用此方式。
2. cloak_read_page() — 提取整洁的 Markdown。用于阅读内容，不用于交互。
3. cloak_screenshot() — 带有元素索引的注释屏幕截图。用于获取视觉上下文（图像、图表、CAPTCHA）。

默认启用隐身功能

所有反检测功能默认开启：

• 源码修补版 Chromium 二进制文件（不是 Playwright 补丁，而是对 Chromium 源码的实际修改）
• 拟人化的鼠标轨迹、键盘时序和滚动模式（humanize=True）
• 隐身指纹参数（一致的 canvas、WebGL、音频指纹）
• 支持代理，并通过 GeoIP 检测时区和区域设置

工具

核心工具（20 个 — 始终可用）

工具	描述
cloak_launch	启动隐身浏览器（所有反检测功能均已开启）
cloak_close	关闭浏览器并释放资源
cloak_snapshot	主要工具 — 带有 [@eN] 引用的无障碍树
cloak_click	按引用 ID 点击元素（自动重试）
cloak_type	按引用 ID 在输入框中输入（可选择提交）
cloak_select	按引用 ID 选择下拉选项
cloak_hover	将鼠标悬停在按引用 ID 指定的元素上
cloak_check	按引用 ID 勾选/取消勾选复选框
cloak_read_page	将页面内容提取为整洁的 Markdown
cloak_screenshot	带有元素索引的注释屏幕截图
cloak_navigate	前往 URL（自动等待页面稳定）
cloak_back	在历史记录中后退
cloak_forward	在历史记录中前进
cloak_press_key	按下键盘按键
cloak_scroll	向上/向下滚动页面
cloak_wait	等待页面稳定
cloak_evaluate	在页面中执行 JavaScript
cloak_new_page	打开新页面/标签页
cloak_list_pages	列出所有已打开的页面
cloak_close_page	关闭指定页面

能力门控工具（通过 --caps 启用）

使用 cloakbrowsermcp --caps network,cookies,pdf,console 或 --caps all 启用。

工具	能力	描述
cloak_network_intercept	network	拦截/模拟/放行请求
cloak_network_continue	network	移除拦截规则
cloak_get_cookies	cookies	获取所有 Cookie
cloak_set_cookies	cookies	设置 Cookie
cloak_pdf	pdf	将页面保存为 PDF
cloak_console	console	获取浏览器控制台输出

配置

CLI 选项

cloakbrowsermcp [--caps CAPS] [--transport {stdio,sse}] [--port PORT]

• --caps：逗号分隔的功能：network、cookies、pdf、console、all
• --transport：MCP 传输方式 — stdio（默认）或 sse
• --port：SSE 传输方式使用的端口（默认值：8931）

环境变量

变量	默认值	描述
CLOAKBROWSER_LOG_LEVEL	INFO	日志级别
CLOAKBROWSER_LOG_FILE	~/.cloakbrowser/logs/server.log	日志文件路径
CLOAKBROWSER_LOG_STDERR	false	同时将日志写入 stderr

启动选项

cloak_launch(
    headless=True,        # False for headed mode (some sites require it)
    proxy="http://...",   # Residential proxy recommended
    humanize=True,        # Human-like input (ON by default)
    stealth_args=True,    # Stealth fingerprints (ON by default)
    timezone="America/New_York",
    locale="en-US",
    geoip=False,          # Auto-detect from proxy IP
    fingerprint_seed="my-identity",  # Consistent fingerprint across sessions
    user_data_dir="/path",  # Persistent profile
)

后端说明：SessionConfig.backend 已弃用。CloakBrowser 0.4.0 移除了 patchright 后端（它会导致代理身份验证和 add_init_script 出现问题，且并未提升隐身效果），因此当前版本会忽略该设置，并仅记录一次 警告。如果仍需要使用它，pip install "cloakbrowsermcp[patchright]" 会固定到 cloakbrowser<0.4，旧版后端在该版本中仍可正常工作，但会带有 上游的这些问题。

架构

cloakbrowsermcp/
├── server.py      # FastMCP server, tool registration, error handling
├── session.py     # Browser lifecycle, page management, ref storage
├── snapshot.py    # Accessibility tree JS, ref resolution
├── markdown.py    # Readability-style HTML-to-markdown extraction
├── vision.py      # Annotated screenshots with element indices
├── waiting.py     # Smart wait, page settle, retry logic
├── stealth.py     # Stealth config inspection
├── network.py     # Network intercept, cookies (capability-gated)
├── __init__.py
└── __main__.py

设计原则

1. 快照优先 — 工具描述引导模型将 cloak_snapshot() 用作主要的页面理解工具
2. 仅使用引用 — 不提供 CSS 选择器工具。所有交互均通过快照中的 [@eN] 引用完成
3. 默认隐身 — 无需配置即可启用所有反检测、拟人化和隐身参数
4. 操作后自动生成快照 — 点击、输入和导航操作都会返回更新后的快照
5. 智能等待 — 导航时自动等待（networkidle + MutationObserver 稳定），点击失败时自动重试
6. 按功能启用 — 默认关闭高级工具（网络、Cookie、PDF），以减少工具数量
7. 清晰地提取内容 — 阅读时使用 Markdown，交互时使用快照，视觉处理时使用带注释的屏幕截图

开发

git clone https://github.com/overtimepog/CloakMCP
cd CloakMCP
pip install -e ".[dev]"
pytest

许可证

Apache-2.0