Browserbase

@mindstone/mcp-server-browserbase

Browserbase API によるクラウドブラウザー自動化：ライブビューでのデバッグに対応したセッション、AI ウェブエージェント、永続コンテキスト、ダウンロード、取得／検索、サーバーレス関数。

MCP ホスト全体に対応した Browserbase API をカバーするローカルのブラウザー自動化コネクターを必要とする場合に最適です。「ブラウザーを開いて見せて」から「価格データを抽出するエージェントを実行して」まで対応します。

ステータス

• バージョン： 0.1.1 · npm
• 認証： API キー（BROWSERBASE_API_KEY）
• ツール： 53（プロジェクト、セッション、コンテキスト、エージェント、エージェント実行、ダウンロード、拡張機能、証明書、取得／検索、関数）
• 対象： クラウド API
• 機械可読： STATUS.json

このパッケージの目的

Browserbase の API は、生の CDP セッションから完全管理型の AI エージェントまで、幅広い機能をカバーしています。このパッケージは、意図的な安全策を組み込みながら、そのすべてをローカルの stdio MCP ホスト向けの単一コネクターとして提供します。セッションの課金についてはツールの説明で明示し、破壊的な操作には注記を付け、外部のウェブコンテンツは常に信頼できないデータとして扱い、長時間実行される処理はポーリングします（Browserbase にはウェブフックがありません）。

やり取りの例

「example.com から料金プランを抽出して、JSON で提示してください。」

ホストが呼び出すツール：

1. create_agent_run — タスクと JSON の形式を指定する result_schema を使って実行を開始します。
2. wait_for_agent_run — 実行が完了するまでポーリングし、構造化された結果を返します。
3. get_agent_run_messages — （任意）エージェントが行った操作を手順ごとに表示します。

応答（抜粋）：

{
  "ok": true,
  "runId": "r0a0b0c0-…",
  "status": "COMPLETED",
  "result": { "plans": [ { "name": "…", "price": 0 } ] },
  "waited_seconds": 47
}

要件

• Node.js 20+
• npm
• Browserbase API キー（browserbase.com/settings）。

ワンクリックインストール

ボタンをクリックすると、ホストから BROWSERBASE_API_KEY の入力を求められます。

{
  "mcpServers": {
    "Browserbase": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": ""
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/browserbase
npm install
npm run build

npx

npx -y @mindstone/mcp-server-browserbase

ローカル

node dist/index.js

設定

認証情報ブリッジを提供するホスト内で実行する場合、configure_browserbase_api_key は環境変数ではなく、ホスト経由でキーを保存します。

MCP ホストの設定

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key"
      }
    }
  }
}

セキュリティに関する注意事項

セッションには料金が発生します — 解放してください

create_session を実行するたびに、課金対象のブラウザーが起動します（分単位、最低 1 分）。create_session と end_session の説明ではエージェントにこの点を明示しており、自動化が完了したらすぐに end_session を呼び出してください。プロジェクトの同時実行数の上限を超えると、429 が返されます。エラー解決情報には retry-after の待機時間がそのまま表示されます。

ライブビュー URL は操作権限を付与します

get_session は認証情報を含む connectUrl を返し、get_session_debug_urls はデバッガー／ライブビューの URL を返します。これらの URL を知っている人は誰でも、ブラウザーを閲覧し、操作できます。URL はセッションの所有者との共有に限り、公開してはいけません。

外部コンテンツは常にラップされます

アカウント外で作成されたコンテンツ（取得したページの内容、検索結果、デバッグ URL 内のページタイトル、エージェント実行のタスク／結果／メッセージ、CDP ログ本文、リプレイプレイリスト、ダウンロードしたファイル名、関数の出力、エラーの詳細など）はすべて、モデルに渡される前に <untrusted-content source="browserbase:…"> 形式のエンベロープでラップされ、閉じタグのブレークアウトをエスケープします。CDP ログの rawBody 値はさらに、約 4KB を超える部分が切り詰められ、切り詰めたことを示す注記が付加されます。

ファイルのアップロードはワークスペース内に制限されます

upload_session_file、upload_extension、upload_certificate は、ローカルの file_path を受け取ります。読み込みは MCP_WORKSPACE_PATH 内（未設定の場合はシステムの一時ディレクトリ内）に制限され、正規化したパスのプレフィックスに基づいて範囲が判定されます。.. によるパス遡及、サンドボックス外の絶対パス、サンドボックス外を指すシンボリックリンクは、ディスクから読み込む前に拒否されます。読み込みは、ファイルを開いてから検証する方式です。コネクターはファイル記述子を開き、開いた inode がサンドボックスによって許可されたファイルと一致することを確認したうえで、その記述子を使って読み込み、読み込み後に再確認します。読み込み中にファイルが入れ替えられたり変更されたりした場合は、安全側に倒して処理を失敗させます。

fetch_url で内部ネットワークを調査することはできません

fetch_url（および、次に取得する可能性のある検索結果に埋め込まれた URL）は、公開 URL のチェックによって保護されています。http://／https:// スキームのみが許可され、localhost、ループバック、リンクローカル、プライベート IP アドレスの範囲はリクエストが送信される前に拒否されます。

削除および停止ツールには破壊的操作の注釈が付いています

delete_context、delete_agent、delete_download、delete_extension、delete_certificate、end_session、stop_agent_run、invoke_function、およびすべての create_*／upload_* ツールには destructiveHint: true が付いています。削除は取り消せません。ホストはユーザーに明示的な確認を求めてください。

ツール（53）

設定

• configure_browserbase_api_key — Browserbase API キーを保存します（ブリッジがある場合はホストに保存されます）

プロジェクト

• list_projects — プロジェクトの一覧（ID、同時実行数の上限、デフォルトのタイムアウト）を取得します
• get_project — プロジェクトの詳細を取得します
• get_project_usage — 使用したブラウザー時間（分）とプロキシのデータ量（バイト）を取得します

セッション

• create_session — クラウドブラウザーセッションを作成します（分単位で課金。connectUrl を返します）
• list_sessions — セッションを一覧表示します。ステータスまたは userMetadata クエリで絞り込めます
• get_session — セッションのステータスと connectUrl を取得します
• end_session — セッションを解放します（REQUEST_RELEASE のセマンティクス。セッションは自動的にも期限切れになります）
• get_session_debug_urls — 人と共有できるライブビューおよびデバッガーの URL を取得します
• get_session_logs — CDP レベルのセッションログを取得します（生の本文は約 4 KB を超えると切り捨てられます）
• get_session_replays — 再生可能な録画済みページを一覧表示します
• get_session_replay_playlist — ページの m3u8 再生プレイリストを取得します
• request_session_recording_downloads — 非同期の MP4 作成をリクエストします（HTTP 202）
• get_session_recording_downloads — MP4 のステータスをポーリングし、有効期間の短い署名付き URL を取得します
• upload_session_file — サンドボックス化されたローカルファイルをセッション内の /tmp/.uploads/ にアップロードします

コンテキスト（永続的なブラウザ状態）

• create_context — セッションをまたいで Cookie／ストレージを保持するコンテキストを作成します
• get_context — コンテキストの詳細を取得します
• delete_context — コンテキストを完全に削除します

エージェント

• create_agent — 再利用可能なエージェントを作成します（名前、システムプロンプト、結果スキーマ）
• list_agents — エージェントを一覧表示します（カーソルによるページネーション、日付で絞り込み可能）
• get_agent — エージェントのプロンプトと結果スキーマを取得します
• update_agent — エージェントを部分的に更新します
• delete_agent — エージェントを削除します（既存の実行には影響しません）

エージェントの実行

• create_agent_run — 実行を開始します（アドホック、またはエージェントを指定。機密情報には %variable% 置換を使用）
• list_agent_runs — 実行を一覧表示します（カーソルによるページネーション、絞り込み可能）
• get_agent_run — 実行のステータスと最終結果／原因を取得します
• wait_for_agent_run — 推奨：最終状態になるまでポーリングし、結果を返します
• get_agent_run_messages — 実行の UIMessage 会話を取得します（since/nextSince フィード）
• stop_agent_run — 実行中の実行を停止します（202。すでに最終状態の場合は 409）

ダウンロード（セッション内でダウンロードされたファイル）

• list_downloads — セッションのダウンロードを一覧表示します（オフセットによるページネーション、絞り込み可能）
• get_download_info — メタデータを取得します（サイズ、チェックサム、MIME タイプ）
• get_download_file — バイト列を base64 として取得します（インライン上限は 8 MB）
• delete_download — ダウンロードを完全に削除します

拡張機能

• upload_extension — ZIP 形式の Chrome 拡張機能をアップロードします（ファイル読み取りはサンドボックス化）
• get_extension — アップロード済みの拡張機能を取得します
• delete_extension — 拡張機能を完全に削除します

証明書

• upload_certificate — TLS を検査するプロキシ用の CA 証明書をアップロードします
• list_certificates — アップロード済みの証明書を一覧表示します
• get_certificate — 証明書を取得します
• delete_certificate — 証明書を完全に削除します

フェッチと検索

• fetch_url — サーバー側で取得します：生の本文、Markdown、またはスキーマ駆動型 JSON
• web_search — ランク付けされた結果を返すウェブ検索

関数（サーバーレスのブラウザー自動化 — 一覧表示／呼び出し／確認のみ）

• list_functions — デプロイ済みの関数を一覧表示します
• get_function — 関数を取得します
• invoke_function — 関数を呼び出します（非同期 202。呼び出しをポーリングしてください）
• list_function_versions — 関数のバージョンを一覧表示します
• get_function_version — バージョンの userParamsSchema を取得します（呼び出し前に確認してください）
• list_function_invocations — バージョンの呼び出しを一覧表示します
• get_function_invocation — 呼び出しのステータス、結果、原因を取得します
• get_function_invocation_logs — 呼び出しのログを取得します
• list_function_builds — 関数のビルドを一覧表示します
• get_function_build — ビルドのステータスと失敗原因を取得します
• get_function_build_logs — ビルドのログを取得します

API カバレッジに関する注意事項

• 上流で非推奨： GET /sessions/{id}/recording（rrweb イベントダンプ）は Browserbase によって非推奨となっており、非推奨を示す 404 が返されるため、意図的に公開していません。代わりに、get_session_replays / get_session_replay_playlist（視聴可能）または録画ダウンロードツール（MP4 ファイル）を使用してください。
• Webhook はありません： Browserbase はポーリング方式です。エージェントの実行（wait_for_agent_run / get_agent_run）、録画のダウンロード（get_session_recording_downloads）、関数の呼び出し（get_function_invocation）はすべてポーリングで取得します。
• コンテキストや拡張機能の一覧取得エンドポイントはありません — 作成時に返される ID を記録してください。
• 関数のデプロイには Browserbase CLI のみを使用します — このコネクターでは既存の関数の一覧表示、確認、呼び出しが可能ですが、作成はできません。

エラー処理

すべての上流エラーは、ok: false、意味を表す code（AUTH_REQUIRED、VALIDATION_FAILED、NOT_FOUND、CONFLICT、GONE、RATE_LIMITED、PAYMENT_REQUIRED、UPSTREAM_ERROR、TIMEOUT、…）、および具体的な対処方法を示す resolution を含む構造化 JSON として返されます。レート制限エラーには、サーバーから提供される retry-after の期間が含まれます。上流のエラーテキストは信頼できないコンテンツとしてラップされ、API キーが出力に含まれることはありません。

ライセンス

FSL-1.1-MIT — Functional Source License, Version 1.1。将来的に MIT ライセンスへ移行します。このソフトウェアは 2030-04-08 に MIT ライセンスへ移行します。