Eyebrowse

---

EyeBrowse を選ぶ理由

• 🥷 デフォルトでステルス — エンジンレベルのフィンガープリント偽装（標準で geoip と humanize が有効。起動ごとに新しいフィンガープリントを生成）；navigator.webdriver を隠し、偽装した画面サイズに合わせてビューポートを自動調整します。puppeteer-extra のようなその場しのぎの対策は不要です。検出回避機能はブラウザーにコンパイルされて組み込まれています。
• 🤖 LLM 向けに設計 — ページは [ref=…] ハンドル付きの ARIA ツリーとして読み取ります。モデルは扱いにくい CSS や生のピクセルではなく、ref を指定して操作（click／type／hover）します。クロスオリジン iframe、シャドウ DOM、ポップアップにも対応しています。
• ⚡ Chrome DevTools Protocol — ノード ref による信頼できるカーソル不要のクリック（Input.dispatchMouseEvent）、Network／Performance／Emulation への直接アクセス、MHTML スナップショット、PDF 出力、ネイティブ動画など、すべてをツールとして利用できます。
• 🧰 1 つのコードベースでライブラリと MCP の両方に対応 — シンプルな Python API（EyeBrowse + Session）と、それを 1 対 1 で反映した軽量な MCP サーバー（85 個の browser_* ツール）を提供し、Claude Code やあらゆる MCP クライアントから利用できます。
• 🪟 機能を制限しません — 厳選された高レベル API でも Playwright の機能を隠しません。ラップされていない機能も session.page／.context／.browser から利用できます。
• 🔋 必要な機能を標準搭載 — マルチセッション、プロキシと ID のローテーション、API モードの CAPTCHA ソルバー、ネイティブ動画、完全な HAR キャプチャ、Markdown 形式でのクリーンな抽出に対応しています。

対象範囲。 EyeBrowse は低レベルのブラウザーエンジンであり、ワークフローロジックは持ちません。 何をするかは利用側が決定し、エンジンは実行可能な操作を提供します。

目次

クイックスタート · インストール · 機能 · 比較 · ライブラリとして利用 · MCP · プロキシと ID · 抽出 · 記録 · 仕組み · 注意事項 · ツール · ライセンス

クイックスタート

pip install eyebrowse
# The stealth-Chromium binary downloads automatically on first launch — nothing else to run.

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                          # stealth defaults: geoip · humanize
    async with eb.session() as s:
        await s.navigate("https://example.com")
        print(await s.snapshot())             # ARIA tree with [ref=...] handles
        await s.click("e6")                   # act on a ref from the snapshot
    await eb.aclose()

asyncio.run(main())

…または Claude Code（あるいは任意の MCP クライアント）に組み込む方法については、MCP 経由で利用をご覧ください。

インストール

PyPI から

pip install eyebrowse                 # or: uv pip install eyebrowse
# CloakBrowser fetches its Chromium binary lazily on first launch — nothing to run.
pip install "eyebrowse[extract]"     # optional: + Crawl4AI markdown extraction (heavier)

ソースから（開発用）

git clone https://github.com/Evil-Bane/eyebrowse && cd eyebrowse
uv sync                              # core engine  (add --extra extract for Crawl4AI)
cp .env.example .env                 # only if you use a proxy / captcha keys

Python 3.12（<3.13 に固定）。エンジン：cloakbrowser>=0.3（ステルス Chromium、Chrome/146）。基盤は playwright 1.60 と mcp 1.27 です。

特長

🥷 ステルス	CloakBrowser のパッチ適用済み Chromium によるフィンガープリント偽装（起動ごとに新しい --fingerprint を使用）。デフォルトで geoip と humanize を使用し、webdriver を隠蔽。ビューポートは偽装した画面に合わせます。
🤖 LLM とのインタラクション	aria_snapshot(mode="ai") → ARIA ツリーと [ref] ハンドル。クリック／入力／ホバー／選択／ドラッグ／ファイルアップロード／ダイアログ／キーボード操作に対応し、座標によるマウス操作も可能です。
⚡ CDP	ref による信頼済みカーソルレスクリック、生の CDP（Network／Performance／Emulation）、MHTML キャプチャ、PDF エクスポート。
🪟 フレームと DOM	ref によるクロスオリジン iframe のルーティング、シャドウ DOM の貫通、ポップアップ／新しいタブの切り替え、任意のフレーム内での evaluate。
🗂 複数セッション	独立したステルスセッション。それぞれが独自のコンテキスト／ID／プロキシを持ちます。
🌐 ネットワーク	リクエスト／レスポンスを検査（XHR／fetch の本文と WebSocket フレームを含む）、URL のブロック、レスポンスのモック、オフラインへの切り替え、HAR の完全なエクスポート。
💾 状態	Cookie、localStorage、sessionStorage（CRUD）、storage_state の保存／再読み込み。
🪪 ID のローテーション	新しいフィンガープリント＋分離されたプロファイル＋ペアリングされたプロキシ。差し替え可能な住宅用 ProxyProvider。
🧩 Captcha	差し替え可能なAPI モードのソルバー（CapSolver／2Captcha／CapMonster／NextCaptcha）＋TOTP。ブラウザー拡張機能は不要です。
📄 抽出	Crawl4AI raw: フィード → クリーンでトークン効率の高いマークダウン（LLM と API キーは不要）。
🎥 キャプチャ	スクリーンショット、Playwright トレース、ネイティブ動画（.webm）。
✅ 検証とデバッグ	アサーション、要素のハイライト、ロケーターの生成、ジオロケーション／ヘッダーのエミュレーション。

ツールごとの完全なリファレンス：docs/TOOLS.md（18 グループにわたる 85 個のツール）。

EyeBrowse の比較

	EyeBrowse	Playwright MCP	browser-use	playwright-stealth
ブラウザーに組み込まれた検出回避機能	✅	❌	❌	⚠️ JS パッチ
LLM ネイティブな ARIA [ref] インタラクションモデル	✅	✅	✅	❌
MCP サーバーを提供	✅（85 個のツール）	✅	⚠️ 一部対応	❌
1 つのコードベース：Python のライブラリと MCP	✅	MCP のみ	ライブラリのみ	ライブラリのみ
完全なCDP（信頼済みクリック・ネットワーク・MHTML・PDF・動画）	✅	⚠️ 一部対応	❌	⚠️ 一部対応
Captcha（API モード）＋TOTP	✅	❌	❌	❌
プロキシ＋ID ローテーションを内蔵	✅	❌	⚠️ 一部対応	❌
クロスオリジン iframe・シャドウ DOM・ポップアップ	✅	✅	⚠️ 一部対応	該当なし

_{公正な比較のための注記：各プロジェクトは異なるニッチを対象としています。この比較は、EyeBrowse が最適化する軸（ステルス性＋LLM による操作性＋単一のライブラリ／MCP コードベース）に基づくものであり、総合ランキングではありません。}

ライブラリとして使う

import asyncio
from eyebrowse import EyeBrowse

async def main():
    eb = EyeBrowse()                           # stealth defaults
    try:
        async with eb.session() as s:          # a stealth session (auto-closed)
            await s.navigate("https://example.com")
            print(await s.snapshot())          # ARIA tree with [ref=...] handles
            await s.click("e6")                # act on a ref
            await s.type("e8", "hello", submit=True)
            png = await s.screenshot(full_page=True)
            title = await s.page.title()        # full Playwright power when you need it
    finally:
        await eb.aclose()

asyncio.run(main())

付属のサンプルを実行します：uv run python examples/direct_usage.py。

MCP 経由での使用

EyeBrowse には MCP サーバー（stdio 経由の FastMCP）eyebrowse-mcp が付属しています。任意の MCP クライアントに追加してください。

Claude Code（CLI）：

claude mcp add eyebrowse -- eyebrowse-mcp

任意の MCP クライアント（JSON 設定）：

{
  "mcpServers": {
    "eyebrowse": {
      "command": "eyebrowse-mcp"
    }
  }
}

続いて、browser_navigate(url) → スナップショットを読む → ref を指定して操作 （browser_click / browser_type / …）というループを実行します。デフォルトのセッションは自動作成されるため、ほとんどのツールはそのまま動作します。全ツール一覧は docs/TOOLS.md をご覧ください。

プロキシとID（任意）

デフォルトではプロキシなしで実行されます（geoip は引き続き、実際の IP に合わせてロケールとタイムゾーンを設定します）。プロキシを使いたい場合にのみ追加してください。

await eb.new_session(proxy="http://user:[email protected]:8080")
await eb.rotate_identity(proxy="socks5://host:1080")   # fresh fingerprint + paired IP
await eb.new_session(no_proxy=True)                     # force proxyless

.env の EYEBROWSE_PROXY_*、eb.set_static_proxy(...)、またはローテーション用のカスタム ProxyProvider で、一度デフォルトを設定できます。MCP 経由では、browser_new_session(proxy_url=…) / browser_new_identity(proxy_url=…) / browser_set_proxy(…) を使います。

reCAPTCHA v3 / レピュテーションによる制限はスコアベースで、IP とセッションのレピュテーションを基準に判定されます。フラグが付いた IP では、新しいブラウザーでもステルス性にかかわらず失敗します。EyeBrowse とクリーンな住宅用プロキシを組み合わせてください。

抽出

eb.extract()（または browser_extract）は、レンダリング済みの HTML を Crawl4AI の raw: フィードに渡し、整理・不要部分の除去がされたマークダウンを返します。LLM は呼び出されず、LLM キーが読み取られることもありません。構造化処理は、利用するエージェントが行います。

md  = await eb.extract()                            # markdown string
res = await eb.extract(output_path="data/page.md")  # → {"path": ..., "chars": ...}

記録

ネイティブ動画 — Playwright はセッション全体を .webm に記録し、終了時に書き出します。パスは事前にわかり、ファイルはセッション終了時に確定します。

s = await eb.new_session(record_video=True)
# ... drive the browser ...
print(await s.video_path())          # path is known up-front; file finalizes on close
await eb.close_session(s.id)

MCP 経由では、browser_new_session(record_video=True) → browser_video_path の順に使います。README 用の GIF が必要ですか？ffmpeg で .webm を変換してください（ffmpeg -i demo.webm demo.gif）。冒頭のデモもこの方法で記録しています。examples/make_demo.py をご覧ください。

仕組み

CONSUMERS                         ENGINE (library: eyebrowse/)
 Claude Code  ──MCP──▶  mcp/  ──▶  EyeBrowse façade (public API)
 your code   ─ import ──────────▶   ├─ BrowserEngine (CloakBrowser / stealth Chromium)
 any MCP client                     ├─ proxy / identity rotation (pluggable)
                                    ├─ captcha solvers (pluggable, API-mode)
                                    └─ Crawl4AI (raw: feed) → clean markdown

ファサード（EyeBrowse + Session）が製品であり、MCP アダプターはその上にある薄い 1:1 のラッパーです。高レベル API は厳選され、LLM が使いやすいように設計されています。Playwright の全機能を再実装したものではありません。生の page / context / browser オブジェクトにも、常に属性を 1 つたどるだけでアクセスできます。エンジン固有の処理はランチャーだけで、それ以外はすべて通常の Playwright です。

注意事項

知っておくとよい点：

• evaluate はページのメインワールドで実行されます（ページのグローバル変数にアクセスできます）。ページのウィジェットのグローバル変数を上書きしてサイトのコールバックを実行する（例：captcha）場合、EyeBrowse は <script> を挿入し、ページのワールドでコードを実行します。captcha/inject.py をご覧ください。
• HAR のエクスポートはセッションを終了します — Playwright が HAR バッファーを書き出すのは、コンテキストが閉じられるときだけです。チェックポイントのパターンを使ってください：browser_storage_state → browser_har_export → browser_new_session(storage_state=...)。JS のコールスタックを含む、イニシエーター情報が豊富な Chrome HAR を取得するには、browser_cdp_send 経由で Network.* ドメインにアクセスします。
• ネイティブ動画は .webm です — 別の形式が必要な場合は、ffmpeg で GIF/MP4 に変換してください。

プロジェクトの構成

eyebrowse/
  api.py            EyeBrowse façade — the single public entry point
  config.py         settings / secrets (pydantic-settings)
  snapshot.py       aria_snapshot(mode="ai") + aria-ref= resolution
  proxy.py          ProxyConfig + pluggable ProxyProvider
  identity.py       Identity + random_identity() (isolated profile dir)
  extract.py        Crawl4AI raw: feed → markdown (lazy, optional dep)
  engine/           engine.py (CloakBrowser launch) + session.py (verbs + registry)
  captcha/          solver ABC + 4 providers + DOM detect/inject
  mcp/              FastMCP server + state + tools/ (18 groups · 85 tools)
examples/direct_usage.py   library proof (no MCP)
examples/make_demo.py      the native-video demo above
docs/TOOLS.md              full tool reference

ビルドに関するメモ、バージョン固定の根拠、検証済みのエンジン動作については、CLAUDE.md をご覧ください。

責任ある使用

EyeBrowse は、検出回避機能を備えた実際のブラウザーを操作します。ご自身が所有するサイト、または自動化の明示的な許可を得ているサイトに対してのみ使用し、利用規約および適用される法律を遵守してください。

ライセンス

MIT © Evil-Bane