Zendriver MCP

zendriver-mcp

MCP 経由で操作する、検出されないブラウザー自動化を LLM エージェントに提供します。

zendriver-mcp は、コーディングエージェント（Claude、Cursor、Gemini、Copilot）が実際のウェブ上で使える、本物の Chrome ブラウザーを提供する MCP サーバーです。Cloudflare の背後やログインが必要なページ、WebDriver を検出してブロックするページでも利用できます。

Zendriver を基盤として構築されています。Zendriver は WebDriver を介さず、Chrome DevTools Protocol と直接通信します。そのため、navigator.webdriver フラグやヘッドレスを示す特徴がなく、一般的な Chrome のインストール環境のように見えるフィンガープリントを実現します。

さらに、エージェントが作業を進めるために必要な機能を zendriver-mcp が備えています。トークン効率の高い DOM ウォーカー、安定した uid を持つアクセシビリティツリー、パフォーマンストレース、Lighthouse 監査、ヒープスナップショット、人間らしい入力、デバイスエミュレーション、Cookie の往復利用など、22 モジュールにわたる 96 個のツールを提供します。

主な特長

• 設計段階から検出されにくい。 Zendriver はクリーンなフィンガープリントを維持します。Cloudflare Turnstile のソルバー、ID のオーバーライド（UA、ロケール、タイムゾーン、位置情報）、ベジェ曲線によるマウス移動、ガウス分布に基づくタイピング間隔も備えています。
• トークン効率の高い DOM。 ページを確認する方法は 2 つあります。生の HTML と比べてトークン数を 96％削減すると報告されている上流の DOM ウォーカーと、再レンダリング後も維持される安定した uid をキーにした CDP アクセシビリティツリーです。
• DevTools と完全に同等の機能。 Chrome DevTools で読み込めるパフォーマンストレース、標準の .heapsnapshot 形式のヒープスナップショット、同じブラウザーを再利用する Lighthouse CLI による Lighthouse 監査を利用できます。
• セッションの往復利用。 HTTP 専用 Cookie を含むすべての Cookie を JSON にエクスポートし、次のセッションで再インポートできます。一度ログインすれば、どこでも再利用できます。
• エミュレーション。 iPhone 15 Pro、Pixel 8、iPad Pro、デスクトップのプリセット、CPU スロットリング、低速 3G／高速 3G／4G／オフラインのネットワークプロファイル、prefers-color-scheme の強制に対応しています。
• スクリーンキャスト。 設定可能な FPS で、フレームを JPEG または PNG としてディスクに書き出します。

ツール一覧

モジュール	ツール
browser	起動、停止、状態確認
navigation	移動、戻る、進む、再読み込み、ページ情報
tabs	新規作成／一覧表示／切り替え／閉じる
elements	クリック、入力、クリア、フォーカス、選択、アップロード
query	要素の検索、テキスト、属性、ボタン、入力欄
content	HTML、テキスト、操作ツリー、スクロール
storage	Cookie（document.cookie）、localStorage
logging	ネットワークログとコンソールログ、リクエスト待機
forms	フォーム入力、送信、キー入力、マウスクリック
utils	スクリーンショット、JS 実行、待機、セキュリティ監査
stealth	Cloudflare の回避、UA／ロケール／タイムゾーン／位置情報のオーバーライド
humanlike	human_click、human_type、estimated_typing_duration
emulation	ビューポート、デバイスプリセット、CPU とネットワークのスロットリング、メディア
devtools	トレースの開始／停止、ヒープスナップショットの取得
lighthouse	監査の実行、CLI の利用可否確認
screencast	開始／停止（フレームのディレクトリに書き込み）
accessibility	安定した uid を持つ AX スナップショット、click_by_uid、describe_uid
cookies	エクスポート／インポート／一覧表示／クリア（CDP レベル、すべてのオリジン）
network_control	URL のブロック、追加ヘッダー、サービスワーカーのバイパス
permissions	許可／リセット、名前の一覧表示
proxy	設定／クリア（プロキシ引数を使ってブラウザーを再起動）
interception	mock_response、fail_requests、一覧表示、停止
screencast	+ export_screencast_mp4、check_ffmpeg_available

完全なシグネチャは src/tools/*.py の docstring に記載されており、MCP ハンドシェイクによって自動的に一覧表示されます。

インストール

PyPI で公開されています：https://pypi.org/project/zendriver-mcp/。

Python 3.10 以降と、Chrome または Chromium のインストールが必要です。

# Zero-setup, re-resolves on every run - great for Claude Desktop configs
uvx zendriver-mcp

# Or install once, invoke many
uv tool install zendriver-mcp
pipx install zendriver-mcp
pip install zendriver-mcp

Claude Desktop／Claude Code での使用

{
  "mcpServers": {
    "zendriver": {
      "command": "uvx",
      "args": ["zendriver-mcp"]
    }
  }
}

クローンも、--directory も、絶対パスも不要です。代わりに永続的にインストールする場合は、uv tool install zendriver-mcp を実行してから、"command": "uvx" を "command": "zendriver-mcp" に置き換えてください。

開発用チェックアウト

zendriver-mcp 自体を開発していますか？クローンして uv sync を実行し、MCP クライアントからチェックアウト先を指定します。

{
  "mcpServers": {
    "zendriver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/zendriver-mcp", "run", "zendriver-mcp"]
    }
  }
}

CLI で指定できるオプションフラグ：

• --browser-path /path/to/chrome - 特定の Chrome バイナリを指定します
• --transport stdio - 現時点では stdio のみです。上流の mcp が 安定したサポートを提供したら、SSE/HTTP に対応します

30秒でわかる概要

# Ask the browser to start, log in once, save the session.
await start_browser()
await navigate("https://example.com/login")
await fill_form({"#email": "[email protected]", "#pw": "..."})
await export_cookies("~/sessions/example.json")

# Next run: skip the login entirely.
await start_browser()
await import_cookies("~/sessions/example.json")
await navigate("https://example.com/dashboard")

# Get an accessibility snapshot, click by stable uid.
snap = await get_accessibility_snapshot()
await click_by_uid("ax_1b2c3d4e")

# Record a performance trace while you click around.
await start_trace()
await human_click(selector="#buy-now")
await stop_trace("/tmp/buy-flow.json")   # loads in Chrome DevTools

# Run Lighthouse against the current browser.
await run_lighthouse("https://example.com", form_factor="mobile")

トークン最適化 DOM ウォーカー

インタラクションツリーは、次のようなコンパクトな行を出力します。 {"id": 1, "t": "btn", "l": "Search", "r": "hdr"}：

• コンパクトなキー：t（タイプ）、l（ラベル）、r（領域）
• スマートラベル：aria-label、aria-labelledby、関連付けられた <label>、placeholder、テキスト、title、alt から推定します
• ノイズのフィルタリング：SVG 内部要素と、ネストされたインタラクティブな子要素をスキップします
• 領域タグ付け：hdr、nav、main、side、ftr、dlg
• タイプの圧縮：button -> btn、checkbox -> chk など

perplexity.ai での削減率は約96％です。生の HTML と比べてトークン数が約11kから 約400に減少しました。

複数のアクションにまたがるフローでは、get_accessibility_snapshot + click_by_uid の使用を推奨します。基盤となるバックエンドノードが存続する限り、 再レンダリング後も UID は有効です。

開発

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

CI では、プッシュと PR のたびに同じ4項目を実行します。

ロードマップ

当初のロードマップにあった項目は、すべて 0.2 / 0.3 リリースで実装済みです。

• ステルス機能：Cloudflare ソルバー、UA / ロケール / タイムゾーン / ジオロケーション
• 人間らしい入力：ベジェ曲線のマウス経路、ガウス分布によるキーストローク間隔
• DevTools との同等機能：トレース、ヒープスナップショット、Lighthouse
• ffmpeg によるスクリーンキャストと mp4 エクスポート
• 安定した UID を持つアクセシビリティツリー
• Cookie のインポート／エクスポート、ブロック、追加ヘッダー、権限
• リクエストのインターセプトとレスポンスのモック（Fetch.enable）
• プロキシ設定（--proxy-server を指定して再起動）
• リッチ出力ツールで ToolResponse エンベロープを採用
• PyPI 公開ワークフロー（Trusted Publishing）

ドキュメントサイト：https://bituq.github.io/zendriver-mcp/

今後の方針は実際の利用状況に基づいて決まります。検討中のアイデア：

• Fetch インターセプトによるリクエストごとのプロキシルーティング
• mock_response でのバイナリ本文のサポート
• パターンを指定した Fetch.enable（「すべてに一致させてからフィルタリング」する現在の方式より高速）

ライセンス

MIT。詳細は LICENSE をご覧ください。

謝辞

• 裏側では Zendriver が大部分の処理を担っています。
• トークン最適化 DOM ウォーカーと、当初の49個のツールの基盤は ShubhamChoulkar/Zendriver-MCP に由来します。 このプロジェクトはフォークとして始まり、現在では独自の方向性と機能セットを備えています。