cloakbrowser-mcp

把 CloakBrowser（在原始碼層改過、繞過 bot 偵測的隱形 Chromium）包成 MCP server，讓 Claude Code（或任何 MCP client）直接拿來做網頁檢索。

底層是真正修改過二進位的 Chromium，連 headless 模式都能通過 sannysoft 的 WebDriver 進階偵測，比 JS 注入式的 stealth 方案穩。

工具

工具	用途
cloak_get_text	開網址回傳渲染後的可見純文字（餵 LLM 分析）；可給 selector 只取某元素
cloak_get_html	回傳渲染後 HTML 原始碼（結構化解析 / 抽連結）
cloak_screenshot	整頁或單一元素截圖存 PNG
cloak_interact	單一 session 內依序執行 click/fill/scroll/wait… 再擷取

每個工具都吃共用反偵測參數：

參數	預設	說明
humanize	false	模擬人類滑鼠曲線 / 鍵盤時序
proxy	null	代理 URL，例如 http://user:pass@host:port（硬站用住宅代理）
geoip	false	依代理 IP 自動對齊時區 / 語系
headless	true	有些站會偵測 headless，硬站設 false
timezone / locale	null	手動指定 IANA 時區 / BCP 47 語系

要繞 Cloudflare / reCAPTCHA / FingerprintJS 時建議組合：住宅 proxy + geoip=true + humanize=true，再不行加 headless=false。

每次呼叫都是「開瀏覽器 → 做事 → 關閉」的無狀態模式；需要跨步驟（登入、填表、翻頁）請用一次 cloak_interact 把動作串起來。

需求

• Python ≥ 3.10（建議 3.12）
• macOS arm64/x64、Linux x86_64/arm64、Windows x86_64
• 首次執行會自動下載隱形 Chromium 二進位（~200MB，快取在 ~/.cloakbrowser/）

安裝

git clone https://github.com/Oliver0804/cloakbrowser-mcp.git
cd cloakbrowser-mcp

python3.12 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -c "import cloakbrowser as cb; cb.ensure_binary()"  # 預先下載 Chromium

註冊到 Claude Code

claude mcp add --scope user cloakbrowser "$(pwd)/.venv/bin/cloakbrowser-mcp"

確認連線：

claude mcp list | grep cloakbrowser   # 應顯示 ✔ Connected

註冊後重開一次 Claude Code session，mcp__cloakbrowser__* 四個工具就會出現。

在 Claude Code 內使用

直接用自然語言叫工具即可，例如：

用 cloak_get_text 幫我抓 https://news.ycombinator.com 的標題
把 https://example.com 用 cloak_screenshot 截整頁存到 /tmp/shot.png
這個站有 Cloudflare，請帶 proxy 跟 humanize 再抓

cloak_interact action 格式

actions 是動作清單，第一個通常是 goto：

[
  {"type": "goto", "url": "https://example.com", "wait_until": "domcontentloaded"},
  {"type": "fill", "selector": "#email", "value": "a@b.com"},
  {"type": "type", "selector": "#q", "value": "hello", "delay": 40},
  {"type": "press", "selector": "#q", "keys": "Enter"},
  {"type": "click", "selector": "button#go"},
  {"type": "select", "selector": "#country", "value": "TW"},
  {"type": "scroll", "dy": 1500},
  {"type": "wait_selector", "selector": ".results", "timeout_ms": 15000},
  {"type": "wait_ms", "ms": 1500}
]

• extract：text | html | none（最終回傳形式）
• selector：extract=text 時只取此元素文字
• screenshot_path：給定則動作跑完後再截一張整頁圖

其他 MCP client

任何支援 stdio 的 MCP client 都能用，把指令指到 entrypoint：

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "/abs/path/cloakbrowser-mcp/.venv/bin/cloakbrowser-mcp"
    }
  }
}

授權

• 本倉庫包裝程式碼：MIT
• CloakBrowser 二進位：免費使用但禁止重新發佈（見上游 BINARY-LICENSE.md）。本倉庫不含二進位，安裝時由 cloakbrowser 套件自動下載。