pilot-mcp — Fast Browser Automation MCP Server

pilot — AI エージェント向けブラウザー自動化 MCP

デフォルトでは、ネイティブの Playwright ベースのブラウザーセッションを使用します。QA 自動化に Chrome 拡張機能は不要です。

Pilot には、2 つのブラウザーバックエンドがあります。

• ネイティブモード（デフォルト）：分離された Playwright ブラウザーコンテキストです。並列 QA 自動化と信頼性の高いスクリーンショットに対応する、推奨される方法です。
• 拡張機能モード（レガシー／オプトイン）：既存の Cookie とログイン済みセッションが必要な場合に、実際の Chrome プロファイルに接続します。

ネイティブモードでは chrome.tabs.captureVisibleTab() を一切使用しないため、スクリーンショットの取得に Chrome が前面に表示されていること、タブがアクティブで表示されていること、拡張機能のサービスワーカーが新しい状態であることは必要ありません。

---

仕組み

AI Agent → MCP Server → Broker on 127.0.0.1:3131 → Native browser session
         (stdio)       (first process owns broker)  (Playwright context/page)

1. Pilot は MCP サーバーとして動作します — Claude Code、Cursor、または任意の MCP クライアントが stdio 経由で接続します
2. 最初に起動した Pilot プロセスが localhost 上のブローカーになります
3. 後から起動した Pilot プロセスはブローカーのクライアントとして接続します
4. 各セッションには、分離されたネイティブのブラウザーコンテキスト／ページが割り当てられます
5. スクリーンショットは Chrome 拡張機能のキャプチャ API ではなく、Playwright から取得します

---

クイックスタート

1. MCP サーバーを追加する

codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- npx -y pilot-mcp

ローカルのチェックアウトを使用する場合：

npm install
npm run build
codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- node /absolute/path/to/pilot/dist/index.js

2. 使用する

「https://example.com を開いて、スクリーンショットを撮り、ページの概要をまとめてください。」

拡張機能のインストールは不要です。Chrome を前面に表示する必要もありません。

ネイティブモードでの全操作、ストレスコマンド、クリーンアップの確認については、docs/native-mode.md をご覧ください。

---

コンパクトなスナップショット

ほかのツールは、ページごとに 50K 文字以上をコンテキストウィンドウに出力します。Pilot は出力を小さく抑えます。

Other tools:   navigate(58K) → navigate(58K) → answer        = 116K chars
Pilot:         navigate(2K)  → navigate(2K)  → snapshot(9K)  =  13K chars

snapshot_diff は、操作間で変更された部分のみを表示し、冗長な再読み込みは行いません。

コンテキストが少ないほど、応答が速くなり、API 呼び出しの費用が抑えられ、幻覚も減ります。

---

Pilot と @playwright/mcp の比較

	Pilot	@playwright/mcp
ブラウザー	デフォルトではネイティブの Playwright コンテキスト、レガシー拡張機能では実際の Chrome	新しい Chromium インスタンス
認証状態	デフォルトではネイティブで分離。拡張機能モードでは実際の Chrome Cookie を使用可能	匿名 — 手動でのセットアップが必要
ボット検出	自動化にはネイティブ、実際のプロファイルへの引き継ぎには拡張機能モード	Cloudflare にブロックされる
スナップショットのサイズ	ナビゲーション時は約 2K、全体では約 9K	約 50～60K
スナップショット差分	pilot_snapshot_diff	❌
Cookie のインポート	Chrome、Arc、Brave、Edge、Comet	手動で JSON を指定
iframe	✅	❌
ツールプロファイル	core（9）／standard（40）／full（69）	--caps グループ
トランスポート	stdio	stdio、HTTP、SSE

---

3 つのプロファイルに 69 個のツール

ツールリストが大きくなるにつれて、LLM の性能は低下します。必要なものだけを読み込んでください。

プロファイル	ツール数	含まれるもの
core	9	navigate、snapshot、click、fill、type、press_key、wait、screenshot、snapshot_diff
standard	40	Core に加え、pilot_act、pilot_guide、evidence、doctor/reset、tabs、scroll、hover、drag、iframes、auth、block、find
full	69	Standard に加え、ネットワークインターセプト、アサーション、クリップボード、位置情報、CDP、evaluate、PDF、レスポンシブ、詳細な検査

{
  "mcpServers": {
    "pilot": {
      "command": "npx",
      "args": ["-y", "pilot-mcp"],
      "env": { "PILOT_PROFILE": "standard" }
    }
  }
}

デフォルトは standard です。ツールの完全なリファレンス →

---

ネイティブモード

ネイティブモードがデフォルトです。

PILOT_BROWSER_MODE=native

QA 自動化、並列 MCP セッション、スクリーンショットによる証跡には、このモードを使用してください。

QA の実行前に確認してください。

PILOT_HEADLESS=1 npm run stress:screenshots
npm run stress:codex

期待される結果：どちらも 6/6 passed と報告します。

Extension モード

Extension モードはレガシー機能で、オプトイン方式です。

PILOT_BROWSER_MODE=extension

ユーザーがすでに認証済みの実際の Chrome プロファイルが必要な場合にのみ使用してください。

実際のブラウザーから Cookie をインポートします：pilot_import_cookies({ browser: "chrome", domains: [".github.com"] })

macOS Keychain ／ Linux libsecret を介して Chrome、Arc、Brave、Edge、Comet に対応しています。CAPTCHA の場合：pilot_handoff → ユーザーが操作 → pilot_resume。

---

要件

• Node.js >= 18
• Playwright Chromium
• macOS または Linux
• Extension モードのみ：Chrome + Pilot 拡張機能

Chromium が見つからない場合：

npx playwright install chromium

セキュリティ

• 拡張機能は localhost のみ（127.0.0.1）で通信します
• ネイティブブローカーは localhost のみ（127.0.0.1）で通信します
• ネイティブセッションでは、MCP セッションごとに分離されたブラウザーコンテキストを使用します
• 出力パスの検証により、PILOT_OUTPUT_DIR の外部への書き込みを防ぎます
• すべてのファイル操作でパストラバーサルを防止します
• PILOT_PROFILE により、公開するツールを制御します（core ／ standard ／ full）

---

クレジット

コアアーキテクチャ — ref ベースの要素選択、スナップショット差分、注釈付きスクリーンショット — は、Garry Tan による gstack から移植しました。Playwright と MCP SDK を基盤に構築されています。

---

Pilot が役に立ったら、リポジトリにスターを付けてください。ほかの人が見つけやすくなります。