Browser MCP

Chrome/Edge ブラウザを、あらゆる AI エージェント向けの MCP ツールとして公開します。Chrome 拡張機能（Manifest V3）自体が MCP サーバーとして動作し、code-mcp-gateway に接続して MCP リクエストにその場で応答します。ローカルサーバーは不要です。code-mcp と同じ JSON-RPC プロトコルを使用するため、既存のエージェント環境にそのまま組み込めます。

仕組み

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

ポップアップで Device ID と Token を入力すると、拡張機能はゲートウェイに直接接続し（登録、25 秒ごとのキープアライブ、75 秒のウォッチドッグ、ジッター付きバックオフ再接続）、initialize / tools/list / tools/call をその場で処理します。ゲートウェイに到達できるエージェントは、ブラウザを操作できます。

オプションのローカルサーバー（browser-mcp.ts）は、ファイルストア（file_read、大容量ダウンロード/アップロード）と、プレーンなローカル MCP HTTP エンドポイントを追加します。ローカルサーバー を参照してください。

クイックスタート

Chrome または Edge 111 以上。Bun 1.1 以上はローカルサーバーまたは開発ツールでのみ必要です。拡張機能自体は単体で動作します。

1. 拡張機能を読み込む。 chrome://extensions を開き、デベロッパーモード を有効にして、パッケージ化されていない拡張機能を読み込む をクリックし、packages/browser-extension を選択します。（または bun browser-mcp.ts を実行し、http://127.0.0.1:7777/extension から zip をダウンロードします。）

2. 接続する。 ツールバーのアイコンをクリックします（接続すると MCP マークが緑色になります）。ゲートウェイの Device ID と Token を入力し、Connect をクリックします。ポップアップに Connected (gateway) と表示されます。

3. 使用する。 任意の MCP クライアントをゲートウェイデバイスに向けます。拡張機能は tools/list に 47 個のツールで応答します。

トークンは、ゲートウェイでこのデバイスに設定されたものと一致している必要があります。ゲートウェイは各リクエストとともにトークンを転送し、拡張機能がそれを検証します。空のままにすると、ゲートウェイに到達できる誰でもブラウザを制御できます。

ローカルサーバー

ファイルストア（file_read、512 KB を超えるダウンロード/アップロード）またはローカル MCP HTTP エンドポイントにのみ必要です：

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

サーバーを実行すると、ポップアップは ID + Token をサーバー自身のゲートウェイリンクにも渡します。サーバーがなくても拡張機能は直接動作します。ローカルクライアントは http://127.0.0.1:7777/mcp を使用します。mcp-client.example.json を参照してください（--token で実行する場合は "headers": { "Authorization": "Bearer <token>" } を追加）。確認：curl -s http://127.0.0.1:7777/health。

code-mcp-gateway によるリモートアクセス

• 直接接続（デフォルト）。 ポップアップに ID + Token を入力します。拡張機能自体が MCP を提供します。ローカルサーバーは不要です。

• サーバーサイドリンク。 ローカルサーバーを使用する場合、ポップアップは wss://code-mcp.tuanm.dev/ws/<id> に接続し、サーバーが HTTP 経由で MCP に応答します。

• CLI（カスタムゲートウェイ）：

  bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

  直接接続モードと同じプロトコルです。ゲートウェイデバイスには同じ --token を使用します。トークンなしでゲートウェイモードを実行しないでください。BMCP_GATEWAY_DOMAIN を設定すると、ポップアップのデフォルトのゲートウェイホストを上書きできます。

ツール（47 個）

@ref システムによる要素検出：snapshot は [ref=eN] マーカー付きのインタラクティブな要素ツリーを返します。すべての操作ツールは ref または CSS セレクターを受け付けます（ref はキャッシュされ自動的に解決されます。古い ref は「run snapshot again」というエラーになります）。

• 検出 — snapshot、find（role/name/text/label/placeholder/title/testid/selector）、get、is

• 操作 — click、dblclick、type、fill、check、uncheck、select、hover、focus、press、drag、scroll、upload

• ナビゲーション — navigate、reload、back、forward、close、tabs、window

• ページ読み取り — extract、execute、screenshot（画像ブロック）、pdf、wait、highlight

• 状態とデバッグ — store、cookies、storage、console、errors、network、status、file_read

• エミュレーションと制御 — emulate、set（viewport/device/geo/offline/headers/media）、perms、auth、dialog、frames、touch、download

コンソール/エラー/ネットワークのキャプチャは最初の呼び出しで開始されます（遅延実行）。そのため、トラフィックをキャプチャするには、有効化後にリロードまたはナビゲートしてください。戻る/進むは CDP ナビゲーション履歴を使用します。完全なスキーマについては、curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' を実行してください。

フラグ

セキュリティ

• Origin ゲート付き。 /browser/ws は chrome-extension:// オリジンのみ受け付けます。/mcp と /files/* は localhost 以外のブラウザオリジンを拒否します。悪意のある Web サイトが localhost 経由でブラウザを操作することはできません（CSRF）。ネイティブ MCP クライアント（Origin ヘッダーなし）は影響を受けません。

• --token は /mcp と /files/* を保護します（?token= または Bearer）。--extension-token は、拡張機能がブリッジで提示する必要があるシークレットを追加します。

• ファイル ID は 12 文字のランダムな 16 進数で、厳密なパターンで検証されます。アップロードのファイル名はサニタイズされます。サイズ上限：アップロード 500 MiB、スクリーンショット 8 MiB インライン。

• chrome.debugger は、アタッチ中に黄色のインフォバーを表示します（同意のシグナル）。perms/cookies は可能な限り非デバッガー API を使用します。

• デフォルトで 127.0.0.1 にバインドします。--token なしで 0.0.0.0 にバインドすると警告が表示されます。

タイムアウト

ブリッジコマンド：デフォルト 30 秒、navigate/execute/wait_for は 60 秒、download/file_upload は 120 秒。ローカルでは 120 秒、ゲートウェイモードでは 55 秒に制限されます（ゲートウェイは 60 秒後にフォワードを中止します）。ツールは bridge_timeout を受け付けて上書きできます。

開発

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server