Chrome Browser Control

stdio MCP ホスト向けのローカル Chrome プロファイル制御

このプロジェクトは、ループバック WebSocket ブローカーに接続された Manifest V3 Chrome 拡張機能を通じて、ブラウザ制御 MCP ツールを公開します。MCP ホストが、拡張機能で入力したものと同じペアリングトークンを使用して stdio アダプターを起動するように設定してください。

リポジトリ: https://github.com/vkongv/chrome-browser-control

前提条件

• Node.js 18+

• Google Chrome

Related MCP server: Tabrix

インストールとセットアップ

推奨パス: CLI をインストールし、その後セットアップを実行します。

npm install -g chrome-browser-control
# or, without a global install:
npx -y chrome-browser-control setup

CLI は cbctl（推奨の短い名前）および chrome-browser-control としてインストールされます。

cbctl setup
cbctl start
cbctl doctor

setup は ~/.chrome-browser-control/config.env（ペアリングトークン + ポート）を書き込み、解凍された拡張機能を ~/.chrome-browser-control/extension にコピーし、MCP ホストのスニペットを出力します。このディレクトリはコミットしないでください。

エージェントスキル（npm とは別）

skills/chrome-browser-control/ 配下のランタイムエージェントスキルは、npm パッケージには含まれません。CLI をインストールした後、エージェントホストがスキルを使用する場合は、このリポジトリ（または skills.sh）からスキルを入手してください。

CLI コマンド（cbctl または chrome-browser-control）:

git チェックアウトから（コントリビューター向け）:

git clone https://github.com/vkongv/chrome-browser-control.git
cd chrome-browser-control
npm install
npm run build
node dist/cli/main.js setup

リポジトリローカルの npm run broker / npm run mcp は、TypeScript ソースに対する開発用として引き続き利用可能です（オプションでリポジトリの .env.local を使用）。

環境変数

• CHROME_BROWSER_CONTROL_TOKEN — 必須。ブローカー、MCP アダプター、拡張機能ポップアップ間で共有される高エントロピーのペアリングトークン。

• CHROME_BROWSER_CONTROL_PORT — WebSocket ブローカーのポート（デフォルト 8765）。

• CHROME_BROWSER_CONTROL_HOST — ブローカーのループバックホスト（デフォルト 127.0.0.1）。

• CHROME_BROWSER_CONTROL_EXTENSION_ID — オプション。ブローカーを特定のインストール済み拡張機能 ID に固定します。

• CHROME_BROWSER_CONTROL_AUTOLOAD — オプション。1 に設定すると、mcp が到達可能なブローカーがない場合にブローカーを起動することがあります（リカバリ）。通常の使用では cbctl start を推奨します。

• CHROME_BROWSER_CONTROL_DISABLE_LOCAL_ENV — オプション。1 に設定すると、リポジトリの .env.local の読み込みをスキップします。

ユーザー設定は ~/.chrome-browser-control/ に保存され、リポジトリの .env.local よりも先に読み込まれます。プロセス環境変数が常に優先されます。

MCP 接続専用デフォルト: cbctl mcp は、すでに実行中のブローカーに接続します。最初に cbctl start でブローカーを起動してください。リカバリには、cbctl mcp --autoload または CHROME_BROWSER_CONTROL_AUTOLOAD=1 を使用します。

拡張機能を読み込む

1. MCP ツールで制御したいプロファイルで Chrome を開きます。

2. chrome://extensions にアクセスします。

3. デベロッパーモードを有効にします。

4. 「パッケージ化されていない拡張機能を読み込む」をクリックします。

5. ~/.chrome-browser-control/extension を選択します（setup で出力されます）。ソースを編集しているコントリビューターは、代わりにリポジトリの extension/ を読み込んでもかまいません。

6. Chrome Browser Control 拡張機能のポップアップを開きます。

7. ローカルポートを変更しない限り、ブリッジ URL を ws://127.0.0.1:8765 のままにします。

8. 生成されたペアリングトークンを貼り付けます。

9. https://example.com、http://localhost:3000 などの許可されたオリジン、またはすべての通常の http:// および https:// ページに対して * を追加します。

10. 「保存して再接続」をクリックします。

拡張機能は、許可されたオリジンに対してホスト権限を要求する場合があります。そのリクエストを拒否すると、それらのオリジンに対するページアクションが実行できなくなります。

* を使用するとローカル開発には便利ですが、現在の Chrome プロファイル内のすべての通常の Web ページが MCP ツールに公開されます。必要なサイトが少ない場合は、明示的なオリジンを推奨します。ワイルドカードモードでは、Chrome が chrome.tabs.captureVisibleTab による表示ビューポートのスクリーンショットを許可するために、オプションの <all_urls> ホスト権限も要求します。バックグラウンドでは、キャプチャ前に非 http(s) URL と許可されていないオリジンをブロックします。

MCP ホストの設定

cbctl setup（または mcp-config）のスニペットを Cursor、Claude Desktop、Codex、またはその他の stdio MCP ホストに貼り付けます。後でホスト固有の設定を再度出力するには:

cbctl mcp-config --host cursor
cbctl mcp-config --host claude
cbctl mcp-config --host codex
cbctl mcp-config --host yaml

MCP サーバーキーは chrome_browser_control です。アダプターコマンドはインストール可能な CLI（cbctl 推奨）で、args: ["mcp"] を使用します（server/index.ts に対して tsx を使用するのではありません）。

YAML スタイルの例:

mcp_servers:
  chrome_browser_control:
    command: "cbctl"
    args: ["mcp"]
    env:
      CHROME_BROWSER_CONTROL_TOKEN: "<generated-token>"
      CHROME_BROWSER_CONTROL_PORT: "8765"
    timeout: 60
    connect_timeout: 30

JSON スタイルの例:

{
  "mcpServers": {
    "chrome_browser_control": {
      "command": "cbctl",
      "args": ["mcp"],
      "env": {
        "CHROME_BROWSER_CONTROL_TOKEN": "<generated-token>",
        "CHROME_BROWSER_CONTROL_PORT": "8765"
      }
    }
  }
}

CLI が PATH にない場合は、setup で出力される NPX フォールバックを使用します: npx に args: ["-y", "chrome-browser-control", "mcp"] を指定します。

MCP ホストが設定ファイルを使用する場合は、そのファイルを非公開に保ち、リポジトリの外に置いてください。

確認

1. ブローカーを起動: cbctl start

2. セットアップチェッカーを実行: cbctl doctor

3. MCP ホストから browser_status ツールを呼び出して確認します。準備ができると、extension.status と ping.status がライブブリッジ接続を示し、extension.allowedOrigins が設定されたスコープを表示します。

ツール

• browser_status: MCP アダプターがブローカーに到達可能かどうか、Chrome 拡張機能が ping に応答するかを確認します。準備ができると、extension.status と ping.status はライブブリッジ接続（古い切断状態のデフォルトではない）を反映し、extension.allowedOrigins は設定されたスコープ（ワイルドカードモードが有効な場合は * (all http/https web origins) を含む）を表示し、extension.session はセッション名/主張されたタブを表示し、protocolVersion / features は読み込まれた解凍済み拡張機能コードを確認します。プロトコルバージョン 6 には document-targeting フィーチャーマーカーが含まれます。

• name_session: ステータス/デバッグ用に人間が読めるセッション名を設定します。

• list_tabs: 拡張機能ポップアップで URL オリジンが許可されているタブを一覧表示します。開いているすべてのタブがフィルタリングされた場合、空の [] ではなく { tabs: [], detail, hiddenTabCount, allowedOrigins? } を返します。ワイルドカードモードは allowedOrigins で明確にラベル付けされます。

• list_frames: Chrome のフレームレジストリを使用して、許可されたタブの現在のフレームドキュメントを一覧表示します。操作可能なアクティブな HTTP(S) ドキュメントには documentId が含まれます。ポリシーでブロックされたもの、ホスト権限が拒否されたもの、サポートされていないもの、フェンス付き、非アクティブな行は、階層/ステータスのみを保持し、URL とドキュメント ID は秘匿されます。

• claim_tab: 許可されたタブをこのブラウザ制御セッションのために主張し、sessionTabId を返します。主張はルーティング状態であり、排他的なブラウザロックではありません。

• release_tab: タブを閉じずに、sessionTabId または tabId による主張を解放します。

• finalize_tabs: タブを閉じずにセッションの主張状態を解放します。keep エントリを渡すと、引き継ぎ/デリバラブルな主張を保持します。

• snapshot: 許可されたドキュメントの簡略化された DOM スナップショットを返します。デフォルトはコンパクトな自動化スナップショットで、簡潔なアクション可能要素、テキストプレビュー（500文字）、省略されたカウント、リージョンサマリーが含まれます。mode: "full" を指定すると、詳細な要素メタデータと text フィールド（デフォルト4000文字）が返されます。mode: "visible" を指定すると、ビューポート/交差認識要素とバウンディングボックスおよびスクロールメタデータが返されます。さらに多くのページ本文テキストが必要な場合は、textLimit（最大 100000）を指定します。textBytesOmitted を確認して、コンテンツが切り詰められたかどうかを判断します。

• visible_snapshot: snapshot({ mode: "visible" }) の便利ツールです。

• navigate: アクティブなタブまたは指定された tabId を許可された URL にナビゲートし、可能な場合はタブの読み込み完了を待機します。デフォルトではフォーカスは変更されません（バックグラウンドタブはバックグラウンドのまま、フォーカスされたタブは非アクティブになりません）。タブを表示可能にする必要がある場合にのみ active: true を渡します。読み込みがタイムアウトした場合、結果には pending: true と warning が含まれます。読み込み待機後に after 観測をサポートします。

• click: 許可されたタブ上のスナップショット参照によって要素をクリックします。after 観測をサポートします。

• type: 許可されたタブ上のスナップショット参照によって要素に入力します。パスワードのようなフィールドは force=true の場合を除いてブロックされます。after 観測をサポートします。

• scroll: deltaX と deltaY によって許可されたタブをスクロールします。オプションの x/y ビューポート座標は、そのポイントの下にスクロール可能な要素がある場合、その要素をスクロールします。スクロールはスナップショットテキストをページ分割しません。スナップショットは完全な document.body innerText を使用します。ページがコンテンツを遅延読み込みする場合を除き、スクロールステッチではなく snapshot で textLimit を増やしてください。after 観測をサポートします。

• query_elements: CSS セレクター、ロール、テキスト、可視性でフィルタリングされた要素の、バウンディングされた参照/ロール/ラベル/バウンディングボックスを返します。

• extract_elements: CSS セレクターからバウンディングされたテキスト/HTML/リンク/時刻データを抽出します。HTML 抽出では、パスワード/OTP/隠しトークン属性値を秘匿し、機密アイテムをマークして、シークレット値が漏洩しないようにします。これは、生の JavaScript 評価に代わるサポートされている方法です。

• screenshot: 許可されたタブの表示ビューポートをデータ URL としてキャプチャします。オプションの ref または bounds（+ padding）はキャプチャ後にトリミングします。空のトリミングは captureVisibleTab の前に失敗します。トリミングなしのレスポンスは crop フィールドを省略します。MV3 キャプチャはビューポートのみです。非アクティブなターゲットタブはキャプチャ前にアクティブ化される場合があります。captureVisibleTab には Chrome が <all_urls> または activeTab を必要とします。この拡張機能はワイルドカード（*）モードでのみオプションの <all_urls> を要求するため、ワイルドカードのスクリーンショットにはそのポップアップ許可が必要です。

• keypress: 一般的な DOM キーボードイベントをページにディスパッチします。ブラウザ/OS レベルのショートカットは MV3 では保証されません。after 観測をサポートします。

• click_at: ビューポート座標でマウスイベントをディスパッチします。after 観測をサポートします。

• wait_for: バウンディングされたセレクター/テキスト/URL 部分文字列条件を待機し、一致/タイムアウトの証拠を返します。

• page_status: タイトル、URL、準備完了/可視状態、ビューポート/スクロール状態、およびイニシエータータイプ別のリソース数を返します。リクエストヘッダーやレスポンスボディは公開しません。

• console_logs: コンテンツスクリプトが注入された後にキャプチャされた、バウンディングされたコンソールログを返します。古いページのコンソール履歴は参照できません。

• collect_scroll: バウンディングされた数のステップをスクロールし（until が設定されている場合はハード上限あり）、各ステップで選択された要素を抽出し、オプションで scroll を介してネストされたスクロールコンテナをターゲットにし、集約アイテム上限（maxItems、デフォルト100）を適用し、オプションで遅延フィードのためにテキストまたは href で重複排除します。オプションの until.noNewItemsForSteps / until.stopBeforeDatetime（ISO-8601; includeTimes が必要）は stoppedReason を設定します。結果には省略/切り詰められたカウントが含まれます。after 観測をサポートします。

• perform_actions: 1回のブローカーラウンドトリップで最大10個の連続ページアクション（click、type、scroll、keypress）を実行します。最初のステップエラーで即座に失敗します。ターミナルの after 観測は、すべてのステップが成功した場合のみ実行されます。座標クリックは単一ツールの click_at に留めてください。ステップに after、tabId、または sessionTabId を含めることはできません。

フレームドキュメントターゲティング

DOM/コンテンツツールは、list_frames によって返されるオプションの documentId を受け入れます。これを省略すると、既存の動作が維持され、各操作の現在のトップドキュメントをターゲットにします。指定すると、その正確なドキュメントを選択します。iframe が移動したり、消えたり、別のタブに移動したり、サポートされなくなったり、アクセスできなくなったりした場合、トップフレームや同じ frameId を使用する置き換えにフォールバックするのではなく、操作は失敗します。

すべてのコンテンツ結果には、バックグラウンドで証明された documentId、frameId、isTopFrame、および coordinateSpace が含まれます。トップフレームの座標は tabViewport を使用します。iframe の visible_snapshot 境界、click_at、および座標スクロールは frameViewport を使用します。screenshot はタブビューポートのみのツールであるため、iframe ローカルの境界をスクリーンショットのクロッピングに渡すことはできません。navigate、screenshot、および list_frames はタブターゲットのみを受け入れます。perform_actions.documentId はバッチ全体に適用され、ステップによって上書きすることはできません。

ドキュメントの失敗は、バッチステップエラーや after の失敗も含め、次のいずれかのプレフィックスを保持します: DOCUMENT_STALE:、DOCUMENT_POLICY_DENIED:、DOCUMENT_HOST_PERMISSION_DENIED:、または DOCUMENT_UNSUPPORTED:。V1 はアクティブな HTTP(S) 最外部/サブフレームドキュメントのみをサポートします。about:blank、about:srcdoc、blob:、data:、オリジンフォールバックフレーム、iframe ナビゲーション、および iframe からタブへのスクリーンショット座標変換は意図的に除外されています。

実行してから観察

アクションツール navigate、click、type、scroll、keypress、click_at、collect_scroll、および perform_actions は、オプションの after オブジェクトを受け入れます。拡張機能は、ベースアクションをコンテンツスクリプトに送信する前に after を削除し、その後、waitFor、snapshot、pageStatus の固定順序で要求された観察を実行します。レスポンスは、ベースアクションの結果に、観察結果を含む after オブジェクトを加えたものです。

perform_actions の場合、after はバッチ全体にのみ適用されます。個々のステップに after を含めることはできず、いずれかのステップが失敗した場合、ターミナル観察はスキップされます。部分的なバッチ失敗は、failedIndex と completedCount を含む構造化されたステップ結果を返し、ブリッジレベルの成功を維持するため、エージェントはペイロードを検査できます。

{
  "ref": "h12",
  "after": {
    "waitFor": { "selector": ".results", "timeoutMs": 5000 },
    "snapshot": { "mode": "visible", "limit": 40 },
    "pageStatus": true
  }
}

after.waitFor には、text、selector、または urlIncludes の少なくとも1つを含める必要があります。timeoutMs はオプションで、最大値は 20000 に制限されているため、実行してから観察するチェーン全体がデフォルトのブローカーリクエストタイムアウト内に収まります。after.snapshot は、デフォルトのスナップショットオプションには true、または mode、textLimit、limit のいずれかを含むオブジェクトにすることができます。無効な after リクエストは、ベースアクションが実行される前に拒否されます。

ベースアクションは成功したが after 観察が失敗した場合、レスポンスにはベースアクションの結果が含まれ、after は { "ok": false, "error": "..." } に設定されます。

スナップショットモードと参照

デフォルトのコンパクトスナップショットは、ブラウザ自動化を維持しながらモデルコンテキストの使用量を削減するように設計されています。コンパクトスナップショットは次のようになります:

{
  "title": "Example Domain",
  "url": "https://example.com/",
  "mode": "compact",
  "elements": [{ "ref": "h1", "role": "link", "label": "Learn more" }],
  "omittedElements": 0,
  "textPreview": "Example Domain ...",
  "textBytesOmitted": 0,
  "regions": []
}

レガシーな詳細要素メタデータが必要な場合にのみ、フルモードを使用してください:

{ "mode": "full", "tabId": 123 }

ビューポートに依存した作業、仮想化されたページ、およびクリック座標の計画には、可視モードを使用してください:

{ "mode": "visible", "sessionTabId": "tab-1" }

長いページコンテンツ（API ドキュメントなど）を読むには、ブローカースクリプトや CDP の回避策を使用する代わりに、textLimit を引き上げてください:

{ "mode": "full", "textLimit": 100000, "tabId": 123 }

コンパクトモードも textLimit を尊重します。本文テキストは textPreview で返されます（コンパクトモードには text フィールドはありません）。textBytesOmitted がゼロより大きい場合、textLimit を増やすか、コンテンツがスクロールしないと読み込まれない遅延読み込みコンテンツである場合に限り、ページをスクロールして再度スナップショットを取得してください。

参照は、出力順序ではなく、要素 ID から割り当てられたドキュメントごとのメモリ内 ID（h...）です。これらは、同じドキュメント内の DOM 挿入/並べ替え全体で安定しており、click / type はコンテンツスクリプトの参照ストアを介して解決されます。参照はフレームドキュメント間で衝突する可能性があるため、結果の documentId を保持し、後続の iframe アクションとともに渡してください。別のページに移動すると新しいドキュメントが読み込まれるため、古い参照は正常に失敗することが予想されます。ナビゲーションまたは主要なページ変更の後は、新しいスナップショットを取得してください。参照ストアは、切断されたエントリ、期限切れのエントリ、および容量を超えたエントリを削除し、古い data-cbc-ref 属性を削除するため、削除された参照が誤って再利用されることはありません。

タブセッション

マルチステップのブラウザ作業の前には、claim_tab を使用することを推奨します:

{ "tabId": 123 }

返された sessionTabId は、snapshot、navigate、click、type、scroll、query_elements、extract_elements、screenshot、wait_for、および関連するページツールに渡すことができます。セッションに現在のクレームがある場合、明示的な tabId または sessionTabId のないページアクションはそのクレームにルーティングされます。クレームがない場合、レガシーなアクティブタブフォールバックが残ります。

クレームは、アドバイザリな MCP ルーティング状態のみです。クレームは、ユーザーがタブを変更、閉じる、または移動することを妨げません。タスクが完了したら、release_tab または finalize_tabs を使用してください。どちらのツールもブラウザのタブを閉じません。

開発チェック

npm test
npm run build
cbctl doctor
# or: node dist/cli/main.js doctor
npm run benchmark:compact-snapshots
npm audit

npm run benchmark:snapshots は、同じコンパクト対フルのベンチマークのエイリアスです。ベンチマークは、コンパクトバイト数、フルバイト数、および削減率を出力します。コンパクトモードは、高密度のフィクスチャで少なくとも 50% 小さく保つ必要があります。

extension/ 下のファイルを編集した後、ブラウザの e2e チェックを実行する前に、chrome://extensions でアンロードされた拡張機能をリロードしてください。アダプター/サーバーの変更後は、MCP ホストも再ビルドして再起動してください。古いロード済みバックグラウンドサービスワーカーまたはツールカタログは、古い動作を提供し続ける可能性があります。browser_status は、両側が最新の場合、adapter.registeredToolCount: 24、拡張機能プロトコルバージョン 6、および document-targeting 機能マーカーを報告する必要があります。

制限事項

• これは、共有ローカルトークンを使用したプロトタイプであり、マルチユーザー認証ではありません。

• ブラウザツールの呼び出しは、ブローカーでグローバルにシリアル化されます。

• コンテンツスクリプトは、完全な Chrome アクセシビリティツリーではなく、DOM スナップショットを使用します。

• 参照は、ドキュメントスコープのメモリ内ハンドルです。ナビゲーション、リロード、主要な DOM 変更、または古い参照エラーの後は、snapshot を再度実行してください。

• 可視スクリーンショットはビューポートのみです。非アクティブなタブをキャプチャすると、Chrome MV3 がウィンドウ内の可視タブをキャプチャするため、そのタブがアクティブになる可能性があります。

• Chrome のスクリーンショットキャプチャには、<all_urls> または activeTab が必要です。このプロジェクトは、ワイルドカードスクリーンショットのためのホスト権限としてのみ、オプションの <all_urls> を要求します。screenshot がこの権限がないと報告した場合、マニフェストの更新後に拡張機能をリロードし、ポップアップを開き、設定を保存し、プロンプトを許可してください。

• keypress と click_at は、CDP 入力ディスパッチではなく、DOM イベントを使用します。これらはページハンドラーには便利ですが、特権ブラウザショートカットやすべてのフレームワーク固有の入力パスをトリガーするとは限りません。

• コンソールログは、コンテンツスクリプトの注入後にのみキャプチャされ、制限があります。

• リソースサマリーは、Performance API からのカウントのみです。リクエストヘッダー、レスポンスボディ、Cookie、ストレージ、履歴、ブックマーク、およびダウンロードは、意図的に公開されていません。

• ブラウザの履歴、ブックマーク、ダウンロード、および Cookie ツールは、意図的に公開されていません。

セキュリティ

• デフォルトのトークンは受け入れられません。ブローカーと MCP アダプターの両方に CHROME_BROWSER_CONTROL_TOKEN を高エントロピーの URL セーフな値に設定し、同じ値を拡張機能のポップアップに貼り付けてください。

• ブローカーは、ループバックホスト 127.0.0.1、localhost、または ::1 にのみバインドします。

• 拡張機能は、オプションのポートを持つ ws://127.0.0.1、ws://localhost、または ws://[::1] にのみ接続します。

• ページアクセスは、ポップアップで構成された許可オリジンによって制限されます。https://example.com などの明示的なエントリを使用するか、* を入力してすべての通常の http:// および https:// Web ページを許可します。構成されたスコープ外のタブおよびページアクションはブロックされます。

• 許可オリジンのチェックは、コンテンツアクション、スクリーンショット、およびタブクレームの前に、拡張機能のバックグラウンドで行われます。

• パスワードのようなフィールドと OTP フィールドは、入力タイプ、自動補完、名前、ID、ラベル、およびプレースホルダーによって検出されます。type は、force=true でない限りそれらをブロックします。

• オプションの CHROME_BROWSER_CONTROL_EXTENSION_ID は、ブローカーを1つのインストール済み拡張機能 ID に固定します。

• CDP フォールバックは、拡張機能のペアリングをバイパスするため、MCP アダプターではサポートされていません。

ブローカーを非ループバックインターフェースにバインドしたり、トークン、ローカル設定ファイル、ログ、または個人のセットアップメモをコミットしたりしないでください。

メンテナー公開

最初の公開 npm リリースは 手動 です。メンテナーは docs/publish-checklist.md に従ってください。デフォルトのリリースパスでは、プッシュ時の自動公開や CI での長期有効な npm トークンを追加しないでください。