CloakMCP

CloakBrowser MCP

AI エージェント向けのステルスブラウザー自動化 — CloakBrowser の検出回避機能と、Playwright MCP に着想を得たアーキテクチャを組み合わせたModel Context Protocolサーバーです。

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 セレクターは不要です。

ページを確認する 3 つの方法

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. ref のみを使用 — CSS セレクタツールはありません。すべての操作で、スナップショットの [@eN] ref を使用します
3. デフォルトでステルス — 設定しなくても、検出回避、人間らしい動作、ステルス引数がすべて有効です
4. 操作後に自動スナップショット — クリック、入力、ナビゲーションを実行すると、更新されたスナップショットが返されます
5. スマート待機 — ナビゲーション時に自動待機し（networkidle と MutationObserver による安定化）、クリックに失敗した場合は自動で再試行します
6. 機能の制限 — ツール数を抑えるため、高度なツール（network、cookies、PDF）はデフォルトで無効です
7. クリーンなコンテンツ抽出 — 読み取りには Markdown、操作にはスナップショット、ビジョンには注釈付きスクリーンショットを使用します

開発

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

ライセンス

Apache-2.0