Stealth Agent Browser

stealth-agent-browser-mcp

AI エージェントにステルス性能に優れた Chromium ブラウザーと、Accessibility-Object-Model と Set-of-Mark ビジョンを組み合わせたインターフェースを提供する Model Context Protocol（MCP）サーバーです。Claude 向けに構築されていますが、MCP 互換のホストであればどれでも動作します。

• ステルスを最優先。 rebrowser-playwright を使用して、playwright-extra クラスのステルスプラグインを回避する Runtime.Enable CDP リークにパッチを適用します。通常の Playwright では失敗する最新のボット検出テスト（CreepJS、bot.sannysoft.com）に合格します。
• デフォルトでトークン消費を抑制。 browser_snapshot は生の HTML（100KB 以上）ではなく、Playwright aria snapshot の YAML（約 2～5 KB）を返します。すべての操作可能な要素には、アクションで直接使用できる [ref=eN] ID が付与されるため、セレクターもズレもありません。
• 必要なときにハイブリッドビジョン。 mode: "hybrid" を指定すると、サーバーはスクリーンショット上に番号付きの赤いボックスを重ね、モデルが視覚的に対象を特定できるようにします（Set-of-Mark プロンプティング、Yang ら）。画像上の ref ID は YAML 内の ID と一致します。同期がずれるような別個の番号体系はありません。
• 可読性に基づくコンテンツ抽出。 browser_scroll_read は JSDOM 経由で Mozilla Readability を実行し、読みやすい Markdown を返します。差分のみの返却も指定でき、変更がなければ再読み込み時のコストはかかりません。
• プロキシに対応。 セッションごとのプロキシ認証に対応しており、レジデンシャルプロキシプールで便利です。

許可された用途に限ります。 ステルスツールには正当な用途があります（アクセシビリティ監査、自分のアカウントの自動化、所有するサイトやテスト許可を得たサイトでの QA など）。サイトの利用規約や適用される法律に違反する目的でこのサーバーを使用しないでください。SECURITY.md を参照してください。

---

インストール

npm install -g stealth-agent-browser-mcp
# Chromium binary is fetched automatically on first launch
npx playwright-core install chromium

または、インストールせずに npx stealth-agent-browser-mcp を実行してください。

クイックスタート（Claude Desktop / Claude Code / Cursor）

MCP 設定に追加します。

{
  "mcpServers": {
    "stealth-browser": {
      "command": "npx",
      "args": ["-y", "stealth-agent-browser-mcp"],
      "env": {
        "SAB_HEADLESS": "true",
        "SAB_STEALTH_LEVEL": "patched"
      }
    }
  }
}

ホストを再起動します。エージェントに以下のツールが表示されます。

ツール

ツール	目的
browser_navigate	URL に移動し、スナップショットを返します。
browser_snapshot	aom（YAML のみ、最も低コスト）、vision（生のスクリーンショット）、または hybrid（YAML と Set-of-Mark スクリーンショット）。
browser_click	[ref=eN] で要素をクリックします。
browser_type	ref で指定した入力欄またはテキストエリアに入力します。
browser_select	ref で指定した <select> の選択肢を選びます。
browser_scroll_read	スクロールして Readability の Markdown を返します（デフォルトでは差分のみ）。
browser_wait_for	テキストまたは ref が表示されるまで待機します。
browser_tabs	list / new / close / switch。
browser_eval	ページの MAIN world で JS 式を評価し、JSON 結果を返します。
browser_set_proxy	単一プロキシの設定を更新します（browser_restart の実行後に有効になります）。
browser_set_proxy_pool	実行中にレジデンシャルプロキシプールを置き換えます（browser_restart の実行後に有効になります）。
browser_solve_captcha	代替 CAPTCHA ソルバー（CapSolver / 2Captcha）。ページ上の Turnstile/hCaptcha/reCAPTCHA を検出します。
browser_restart	現在の設定で、アクティブなブラウザーセッションを閉じて再度開きます。

すべてのアクションツールは、直近の AOM スナップショットに出力された ref で指定します。ref は Playwright 独自の aria-ref=eN ID であり、別個の番号体系はありません。

設定

すべて環境変数で設定します。

変数	デフォルト値	備考
SAB_HEADLESS	true	ウィンドウを表示する場合は false にします（デバッグ用）。
SAB_STEALTH_LEVEL	patched	off | patched | paranoid。
SAB_PROXY_SERVER	—	単一プロキシモードです。例：http://host:port
SAB_PROXY_USERNAME / SAB_PROXY_PASSWORD	—
SAB_PROXY_POOL	—	レジデンシャルプロキシプールです。カンマ区切りの URL（http://u:p@host:port,...）または {server, username, password} の JSON 配列を指定します。
SAB_PROXY_ROTATION	per-restart	per-session | per-restart | static。
SAB_PROXY_STICKY_TEMPLATE	—	スティッキー IP プロバイダー用のユーザー名テンプレートです。${sessionId} が補間されます。例：brd-customer-c1-zone-res-session-${sessionId}。
SAB_HUMAN_MOUSE	true	クリック前にためらいを加えたベジェ曲線のマウス移動を行います。Datadome の軌跡分析を回避します。
SAB_CAPTCHA_PROVIDER	none	capsolver | twocaptcha | none。
SAB_CAPTCHA_API_KEY	—	プロバイダーの API キーです。
SAB_USER_DATA_DIR	—	永続プロファイルディレクトリです（Cookie によって評価が蓄積されます）。
SAB_DEFAULT_TIMEOUT_MS	15000	アクションごとのタイムアウトです。
SAB_MAX_ANNOTATED	75	ハイブリッドモードでラベル付けするボックスの最大数です。
SAB_VIEWPORT_W / SAB_VIEWPORT_H	1366 / 768
SAB_LOCALE	en-US
SAB_TIMEZONE	America/New_York
LOG_LEVEL	info	debug、warn などです。常に標準エラー出力に書き込みます。

アーキテクチャ

src/
├── index.ts         # Entry (stdio)
├── server.ts        # MCP server + tool registration
├── tools.ts         # Tool handlers
├── browser.ts       # Stealth Chromium launcher (rebrowser-playwright)
├── session.ts       # Per-connection browser/context/page state
├── snapshot.ts      # AOM + Set-of-Mark pipeline
├── annotate.ts      # SVG overlay compositing (sharp)
├── reader.ts        # Readability → Markdown (pierces open shadow roots)
├── fingerprint.ts   # Rotatable UA/viewport/timezone profiles
├── proxy.ts         # Residential pool + rotation + sticky-session template
├── human-mouse.ts   # Bezier-curve cursor paths (ghost-cursor math)
├── captcha.ts       # CapSolver / 2Captcha REST adapters
├── config.ts        # Zod-validated env config
└── logger.ts        # pino → stderr (never stdout)

すべてのログは標準エラー出力に書き込みます。標準出力は JSON-RPC 用に確保されています。console.log は追加しないでください。

TLS／JA3 フィンガープリント — Node レイヤーのスプーファーを使わない理由

スクレイパーでは、よく次のような要望があります。「curl-impersonate または node-tls-client を使って TLS ClientHello（JA3）を Chrome に見えるように偽装したい」

これは Node レイヤーの HTTP スクレイパー（fetch、got、axios）に当てはまります。この場合、TCP 接続は Node の OpenSSL から開始され、Chrome の BoringSSL とは異なるシグネチャを持つ ClientHello が送信されます。そのため、Cloudflare／Akamai Bot Manager は JavaScript が 1 バイトでも実行される前に、ネットワークレイヤーで接続を遮断します。

この MCP はそのようなアーキテクチャではありません。 すべてのリクエストは Chromium 経由で送信されます。Chromium の TLS スタックは Chrome の TLS スタックそのもの（文字どおり同じ BoringSSL ビルド）なので、ClientHello の JA3 は構造上、Chrome の JA3 になります。JavaScript レベルで書き換えることはできず、その必要もありません。

TLS で検出される可能性があるのは、TLS を終端して再度開始するプロキシ（MITM）を経由する場合です。レジデンシャルプロキシプロバイダー（Bright Data、DataImpulse、Oxylabs residential、SOAX）は TCP レベルでルーティングし、TLS を MITM しないため、Chromium のハンドシェイクは変更されずにオリジンへ到達します。TLS を MITM する製品には、マネージド型スクレイピングブラウザー（Bright Data の Scraping Browser、Oxylabs Web Unblocker）があります。これらは独自のヘッドレス Chrome を提供し、この MCP にレイヤーを重ねるのではなく、置き換えて使用します。

結論： rebrowser-playwright ＋ レジデンシャルプロキシプール（P1）＋ 人間らしいマウス操作（P2）を使えば、TLS フィンガープリント、CDP ランタイム、DOM サーフェス、動作レイヤーのすべてが実際の Chrome と一致します。Captcha の解決（P3）は、それでも検出されるセッションの 1～5% に対するフォールバックです。

ベンチマーク

npm run bench:stealth は、設定済みのブラウザーを公開されているボット検出テストページ（bot.sannysoft.com、CreepJS、pixelscan、BrowserLeaks WebRTC）にアクセスさせ、合否を報告します。これらは rebrowser-patches プロジェクトと Patchright プロジェクトでも使用されている同じテストハーネスです。リファレンススイートについては、rebrowser-bot-detector を参照してください。

ローカルフィクスチャを使った一般的なテスト実行結果（test/ を参照）：

テスト	結果
AOM YAML にすべてのインタラクティブ要素の refs が含まれている	✓
hybrid モードが PNG と YAML を返し、refs が一致する	✓
refs を指定した click／type で期待どおりの DOM 変更が生じる	✓
Readability が記事を Markdown に抽出する	✓
差分のみのスクロールを繰り返すと (no readable content change) が返る	✓

比較

	stealth-agent-browser-mcp	playwright-mcp	browser-use MCP	computer use
CDP レベルのステルス（Cloudflare/DataDome）	✓	✗	部分的	✗
アクセシビリティツリーのスナップショット	✓	✓	✓	✗
Set-of-Mark ビジョン（参照ラベル付きスクリーンショット）	✓	✗	✗	純粋なビジョン
可読性に基づくスクロールと読み取り	✓	✗	✗	✗
デフォルトでトークン消費を抑制	✓	✓	✗	✗
エージェントループを同梱	✗（ホスト側のモデルが制御）	✗	✓	✗

開発

npm install
npx playwright-core install chromium
npm run build
npm test

コントリビューション

CONTRIBUTING.md を参照してください。すべての貢献は Apache-2.0 の下でライセンスされます。

ライセンス

Apache-2.0