sendblue-browser-mcp

sendblue-browser-use

エージェント向けの独立したデバッグブラウザーです。ステルスパッチを適用した Chromium を小規模な HTTP API の背後で動作させ、名前付きの永続セッション、簡単に使える消去エンドポイント、設定可能な自動スクリーンショット、CDP 接続を備えているため、どのクライアント（Playwright、Puppeteer、undetected-chromedriver、カスタムスクリプト）からでも操作できます。

独立したプロセスとして実行され、特定の Claude / Cursor / Codex セッションにひも付けられません。そのため、複数のエージェントで同時に共有し、互いのフローをデバッグしたり、毎回認証する手間をかけずにログイン済みセッションを再利用したりできます。

これが必要な理由

必要性	得られるもの
単一のエージェントに依存しない	長時間稼働する HTTP デーモンです。ベアラートークンを持つツールなら、どれでも操作できます。
自動化に見えない	patchright で Chromium にパッチを適用します。navigator.webdriver は隠され、CDP の検出ベクトルにはパッチが適用され、本物の Chromium バイナリを使用します（Playwright のフィンガープリントはありません）。一般的な Cloudflare Turnstile など、比較的簡易なチェックを通過します。大規模な悪意あるスクレイピング向けではありません。
セッションを再利用できる	名前付きの永続プロファイルです。一度ログインすれば、その後のデバッグ実行で Cookie が再利用されます。
ワンクリックでリセット	POST /sessions/:name/purge はセッション ID を保持したまま Cookie とアクティブページのストレージを消去するため、クライアントコードをそのまま使用できます。
複数エージェントでの利用に適している	各セッションは独立した BrowserContext（または独自のプロファイル）です。状態が混ざることなく、5 つ以上のデバッグセッションを並行して実行できます。
CDP 接続	GET /sessions/:name/cdp-url は、非永続セッションの共有ブラウザー CDP URL を返すため、Playwright / Puppeteer / 任意の CDP クライアントからデバッグブラウザーに connect() できます。
証拠を自動取得	ナビゲーションのスクリーンショットは NAV_SCREENSHOT_POLICY に従います（デフォルト：ヘッドレス実行時のみ）。Playwright のトレースも任意で取得できます。
HTTP で操作可能	通常の curl が使えます。SDK は不要です。
単体でデプロイ可能	任意の Mac mini / EC2 / Codespace で docker compose up を実行するだけです。ホスト側に Chromium は必要ありません。

クイックスタート（ローカル）

前提条件：PATH に Bun >=1.3 と Node.js >=20 が含まれていること。

git clone https://github.com/sendblue-api/sendblue-browser-use.git
cd sendblue-browser-use
bun install
bun --bun x patchright install chromium

cp .env.example .env
# generate and set the required token
TOKEN="$(openssl rand -hex 32)"
sed -i.bak "s/^BROWSER_USE_API_KEY=.*/BROWSER_USE_API_KEY=$TOKEN/" .env
rm .env.bak

bun run dev

次に、別のターミナルで実行します。

source .env
TOKEN="Authorization: Bearer $BROWSER_USE_API_KEY"

# 1. create a persistent session (log in here once, reuse it forever)
curl -s -X POST http://127.0.0.1:8787/sessions \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"qa","persistent":true}'

# 2. navigate
curl -s -X POST http://127.0.0.1:8787/sessions/qa/navigate \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://trybloom.so/"}'

# 3. screenshot
curl -s http://127.0.0.1:8787/sessions/qa/screenshot?fullPage=true \
  -H "$TOKEN" -o /tmp/qa.png

# 4. wipe state without losing the session
curl -s -X POST http://127.0.0.1:8787/sessions/qa/purge -H "$TOKEN"

クイックスタート（Docker）

echo "BROWSER_USE_API_KEY=$(openssl rand -hex 32)" > .env
docker compose up -d

API は同じで、127.0.0.1:8787 で公開されます。データは ./data/ に保持されます。デフォルトでは CDP はコンテナー内のループバックからのみ利用できます。ホストから CDP を接続するには、信頼できるマシンでのみ、docker-compose.yml 内の CDP_BIND とポートマッピング 127.0.0.1:9222:9222 のコメントを解除してください。

エージェントにインストールする

このリポジトリには 3 種類のパッケージが用意されており、どのエージェントからでも 1 行の設定でデーモンを操作できます。

MCP（Claude Desktop、Codex、Cursor、Antigravity、Cline、Windsurf）

複数のエージェントで使える方法です。HTTP API を MCP ツール（health、create_session、navigate、screenshot、script、get_cdp_url、purge_session など）としてラップします。

{
  "mcpServers": {
    "sendblue-browser": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "BROWSER_USE_URL": "http://127.0.0.1:8787",
        "BROWSER_USE_API_KEY": "<same token you start the daemon with>"
      }
    }
  }
}

~/.cursor/mcp.json、~/Library/Application Support/Claude/claude_desktop_config.json、~/.gemini/config/mcp_config.json などに追加します。Codex の場合：

codex mcp add sendblue-browser \
  --env BROWSER_USE_URL=http://127.0.0.1:8787 \
  --env BROWSER_USE_API_KEY=<daemon-token> \
  -- npx -y [email protected]

ラッパーのソース：mcp/。

Claude Code プラグイン

/plugin install sendblue-api/sendblue-browser-use

このリポジトリから .claude-plugin/plugin.json と skills/sendblue-browser/SKILL.md を取得します。

Codex / Antigravity / Cline スキル

同じ skills/sendblue-browser/SKILL.md を、Codex、Google Antigravity、Cline でスキルとして使用できます。フォルダーを次の場所にコピーしてください。

エージェント	パス
Codex	~/.codex/skills/sendblue-browser/
Antigravity	~/.gemini/skills/sendblue-browser/
Cline	設定で Skills を有効にし、スキルディレクトリに追加

AGENTS.md を使うリポジトリ

リポジトリですでに agents.md の規約を採用している場合、このリポジトリの AGENTS.md は、このデーモンを呼び出すコンシューマーリポジトリ向けのコピー＆ペースト可能なセクションとしても使えます。

API

/health を除くすべてのルートには、Authorization: Bearer $BROWSER_USE_API_KEY が必要です。

メソッド	パス	ボディ／クエリ	戻り値
GET	/health	—	{ ok, service, version, sessions, defaultHeadless, navScreenshotPolicy }
GET	/sessions	—	{ sessions: [...] }
POST	/sessions	{ name, persistent?, headless?, viewport?, userAgent?, locale?, timezone?, traces?, proxy? }	{ session }
GET	/sessions/:name	—	セッション情報 + 現在のページの URL／タイトル
POST	/sessions/:name/purge	—	{ session } — Cookie とアクティブなオリジンのストレージを消去し、セッション ID は維持します
DELETE	/sessions/:name	—	{ ok } — コンテキストを閉じ、プロファイルを削除します
POST	/sessions/:name/navigate	{ url, waitUntil?, timeoutMs? }	{ url, title, status }
GET	/sessions/:name/screenshot	?fullPage=true&selector=...	image/png
POST	/sessions/:name/script	{ code, timeoutMs? }（≤200kB）	{ result } — コードをページのコンテキスト内で実行します
GET	/sessions/:name/cookies	?url=...	{ cookies }
POST	/sessions/:name/cookies	{ cookies: [...] }	{ ok }
GET	/sessions/:name/console	?limit=100	{ messages: [...] }（リングバッファー）
GET	/sessions/:name/cdp-url	—	{ cdpUrl, targetId } — 非永続セッション専用です

POST /sessions/:name/script は、code を Playwright の page.evaluate に直接渡します。JavaScript の式を送信するか、文を IIFE でラップしてください。スクリプトのタイムアウトはデフォルトで 30s です。timeoutMs に最大 120000 を指定するか、0 を指定するとリクエストのタイムアウトを無効にできます。

{ "code": "(() => { const x = 1; return x; })()" }

エラー

2xx 以外のすべてのレスポンスは、同じ形式のエンベロープを使用します。Playwright で発生したエラーは、返される前に 1 行に切り詰められます。完全なメッセージは、プロキシの認証情報を伏せた状態でサーバー側に記録されます。

{ "error": { "code": "navigate_failed", "message": "net::ERR_NAME_NOT_RESOLVED" } }

ステータス	コード	意味
400	empty_body	必須のリクエストボディがありません
400	malformed_json	ボディが有効な JSON ではありません
400	invalid_body	ボディが Zod の検証に失敗しました（error.details を参照）
401	unauthorized	ベアラートークンがないか、正しくありません
404	not_found	セッションが存在しません
409	already_exists	同じ名前のセッションがすでに実行中です
409	cdp_unavailable_for_persistent_session	永続セッションでは共有 CDP URL を公開しません
422	script_failed	/script リクエストは有効でしたが、ページ内の評価で例外が発生したか、タイムアウトしました
500	internal_error	予期しないエラーです。サーバーログを確認してください
502	navigate_failed screenshot_failed cookie_read_failed cookie_write_failed session_unreachable	Chromium 側のエラー

セッションオプション

{
  name: string;            // required, [a-z0-9_-]
  persistent?: boolean;    // default true — profile data survives restarts
  headless?: boolean | "new"; // persistent sessions only; non-persistent uses DEFAULT_HEADLESS
  viewport?: { width, height };
  userAgent?: string;
  locale?: string;         // default "en-US"
  timezone?: string;
  traces?: boolean;        // capture a Playwright trace.zip on session close
  proxy?: { server, username?, password?, bypass? };
}

Cookie の形式

POST /sessions/:name/cookies では、Playwright 形式の Cookie を最大 500 個受け付けます。

{
  cookies: Array<{
    name: string;
    value: string;
    url?: string;       // absolute URL, or domain + path
    domain?: string;
    path?: string;
    expires?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: "Strict" | "Lax" | "None";
  }>;
}

各 Cookie には、url または domain と path の両方を指定する必要があります。

永続セッションと非永続セッション

• persistent: true（デフォルト） — Cookie、localStorage、IndexedDB は ~/.sendblue-browser-use/profiles/<name>/ に永続化されます。デーモンの再起動後、同じ名前の永続セッションを再作成すると、そのプロファイルを再利用できます。各セッションに専用のブラウザーインスタンスが割り当てられるため、これらのセッションでは CDP 接続を利用できません。
• persistent: false — 新しい BrowserContext を介して、中央の Chromium プロセスを共有します。状態はメモリ内にのみ保持されます。/sessions/:name/cdp-url を介した CDP 接続を利用できます。このエンドポイントは、共有ブラウザーレベルの CDP エンドポイントと、セッションのページの targetId を返します。CDP クライアントから共有デバッグブラウザーが見えるため、CDP ポートはローカルの信頼できる環境に限定し、操作前に返されたターゲットを選択してください。

「一度ログインして、1 週間デバッグする」ワークフローには永続セッションを選択してください。Playwright／Puppeteer を直接接続する必要がある場合は、非永続セッションを選択してください。

例

• examples/attach-from-playwright.ts — CDP 経由で Playwright に接続し、ページを操作します（ファイルヘッダーに記載のとおり、Node/tsx で実行します）
• examples/attach-from-puppeteer.ts — Puppeteer を使った同様の例です
• examples/multi-agent-debug.ts — 2 つのエージェントが 2 つのサーフェスを並行して操作します
• examples/run-script.sh — curl のみを使った手順です

ステルスに関する注意事項

これは patchright を基盤としています。patchright は、次の機能を備えたメンテナンス中の Playwright フォークです。

• navigator.webdriver を隠します
• CDP のランタイムマーカーを削除します
• Playwright 固有の拡張機能とコマンドフラグを取り除きます
• 実際の Chromium を使用するため、ほとんどのフィンガープリント項目が通常のユーザーと一致します

デフォルトでは、意図的に --disable-blink-features=AutomationControlled を渡したり、userAgent／viewport をオーバーライドしたりしていません。patchright がこれらを内部で処理し、こちらでオーバーライドすると rebrowser パッチの効果が損なわれるためです。理由がある場合に限り、セッションごとに明示的な userAgent を渡してください。

他の選択肢より patchright を選ぶ理由：

• nodriver／undetected-playwright との比較 — patchright は積極的にメンテナンスされており、Playwright の API を踏襲し、既存の TypeScript エコシステムにスムーズに統合できます。
• Camoufox との比較 — Camoufox は、より深いフィンガープリントのランダム化が可能な Firefox を使用しており、大規模な敵対的スクレイピングに適しています。自社の認証フロー（Clerk、Stripe、Google OAuth、Cloudflare Turnstile）をメンテナンスの負担を増やさずに QA するには、patchright が適しています。

ストレージ

~/.sendblue-browser-use/
├── profiles/
│   └── <session>/          # persistent profile dir
└── runs/
    └── <session>/
        ├── 2026-05-25T...-nav.png   # automatic nav screenshot when policy enables it
        └── 2026-05-25T...-trace.zip # if traces:true at create

POST /sessions/:name/purge は、コンテキスト全体の Cookie と権限を消去した後、現在開いているページ／オリジンの localStorage、sessionStorage、IndexedDB、ServiceWorker の登録、CacheStorage、コンソールバッファーを消去します。永続プロファイル内の過去すべてのオリジンを列挙することはなく、ディスク上のプロファイルも削除しないため（セッション ID は引き続き有効です）、ブラウザーレベルの HTTP キャッシュや HSTS の状態も消去しません。プロファイルも消去するには、DELETE /sessions/:name を実行してから再作成してください。

自動ナビゲーションスクリーンショットは NAV_SCREENSHOT_POLICY に従います。

• headless（デフォルト）：実質的にヘッドレスのセッションのみ *-nav.png を書き込み、ヘッド付きブラウザーでの表示キャプチャーのちらつきを防ぎます。
• always：従来の動作を維持し、ヘッド付きセッションを含むすべてのナビゲーションをキャプチャーします。
• off：自動ナビゲーションスクリーンショットを無効にします。

自動スクリーンショットはセッションごとに MAX_NAV_SCREENSHOTS 枚までに制限されます（デフォルトは 200 枚で、古いものから削除されます）。自動スクリーンショットを完全に無効にするには、MAX_NAV_SCREENSHOTS=0 を設定してください。ヘッド付きブラウザーから証拠が必要な場合は、/screenshot を明示的に呼び出してください。

セキュリティ

• HTTP API はデフォルトで 127.0.0.1 にバインドされます。BIND=0.0.0.0 を設定すると LAN に公開されるため、その前に認証付きリバースプロキシを前段に配置してください。Docker イメージではホストのポート公開が機能するよう BIND=0.0.0.0 に設定されていますが、docker-compose.yml では 127.0.0.1 にのみ公開されます。直接 docker run -p 8787:8787 を実行する場合は、HTTP API を公開することになります。
• CDP は CDP_BIND にバインドされます（デフォルトは 127.0.0.1。Docker イメージのデフォルトもループバックのみです）。デフォルトの docker-compose.yml では CDP は公開されません。ホストからの CDP 接続を有効にする場合は、127.0.0.1 にのみ公開してください。このポートに接続できる人は、ブラウザー内で完全な RCE を実行できます。ループバックに限定してください。
• POST /sessions/:name/script はページのコンテキストで任意の JS を実行します。唯一の認証手段はベアラートークンです。トークンを共有しないでください。
• ベアラートークンは、ローカルのブラウザー／ネットワークを制御できるものとして扱ってください。トークンを持つ人は、デーモンホストから到達可能な任意の http(s) URL に Chromium を移動させることができ、localhost やプライベートネットワーク上のサービスも含まれます。
• POST /sessions/:name/navigate が受け付けるのは http(s) URL のみです。file://、chrome:// などは拒否されます。
• ヘルスチェック（GET /health）は、Docker／k8s のプローブがトークンなしで動作できるよう公開されています。返されるのはサービスのメタデータのみです。

Architecture

HTTP :8787  ──►  Hono router  ──►  session manager  ──►  patchright Chromium
                                    │                    └─►  CDP :9222 (loopback; Docker opt-in)
                                    └─►  on-disk profiles + runs

Inspired by the Sendblue channel-server pattern (Bun + Hono + bearer auth + simple HTTP surface).

License

MIT. See LICENSE.