MCP Browser Extension

MCP Browser Extension

ウェブサイトとドキュメント： mcp-browser-extension.com · クイックスタート · 全43種類のツール · Chrome ウェブストアから拡張機能をインストール

すでにログインしている Chrome を Claude に使わせましょう。 どのサイトにも見知らぬ相手としてアクセスする、新しい自動ブラウザーではありません。あなたのセッション、Cookie、そして設定済みの2FAを使える、あなたの Chrome です。ブラウザーでページを表示できるなら、エージェントは再ログインしたり、認証情報をどこかに貼り付けたりせずに、そのページを読み取れます。

多くのブラウザー MCP サーバーは独自の Chromium を起動し、ログアウト状態のウィンドウをエージェントに渡します。MCP Browser Extension はその逆です。MV3 拡張機能が localhost の WebSocket サーバーに接続し、chrome.scripting／chrome.tabs を通じて、すでに開いているブラウザーを操作します。Claude Code、Claude Desktop、その他あらゆる MCP ホストで動作します。

MCP Browser Extension は、拡張機能と、npx で実行する小さな MCP サーバーの2つで構成されます（npm パッケージおよびコマンド：mcp-browser-extension）。拡張機能は Chrome ウェブストア から入手するか、展開した状態で読み込めます。

このビルドは拡張機能のみです。 Chromium を独自に起動したり接続したりすることはないため、拡張機能は任意ではなく必須です。拡張機能がなければ、どのツールも実行できません。CDP フラグ（--cdp-fallback、--no-cdp-fallback、--cdp-endpoint、--prefer）は後方互換性のため引き続き受け付けますが、無視されます。

設計の全容： docs/BLUEPRINT.md — アーキテクチャ、ワイヤープロトコル、すべてのツールの概要、拡張機能のマニフェスト、セキュリティモデル、段階的なビルド計画。

ログイン済みの Chrome で Claude を使う

Gmail、GitHub、分析ダッシュボード、管理パネル、CRM には、すでにログインしています。MCP Browser Extension を使うと、Claude（Claude Code、Claude Desktop、その他の MCP ホスト）が同じタブで作業できます。再ログインも、2 回目の 2FA プロンプトも、設定ファイル内のパスワードや Cookie も不要です。この拡張機能は通常の Chrome 内で動作するため、エージェントが開くページは、あなたが見るページと同じです。

• Gmail — すでに開いているタブで、スレッドや検索結果を読み取ります。
• GitHub — プライベートリポジトリを含め、あなた自身として PR、issue、設定ページを確認します。
• ダッシュボード — API がない、または API を設定していない分析、請求、管理画面から数値を取得します。

ほかにも、ログイン済みの Chrome を操作するツール（たとえば hangwin/mcp-chrome 拡張機能）があります。そこで重要なのは、セッションに加えて何が得られるかです。

• ドメインごとの許可リスト。デフォルトではすべて拒否です。 フラグがない場合、エージェントは何も読み取れません。--allow-domain mail.google.com --allow-domain github.com を指定すると、そのホストだけが許可されます（*.example.com はドメインとそのサブドメインを対象にします）。ほかのすべてのサイトは、ページにリクエストが届く前に拒否されます。読み取りも制限の対象で、クリックだけではありません。また、拡張機能側でも同じポリシーを再確認します。変更、評価、ダウンロード、アップロードは、それぞれ個別に明示的な許可が必要です。
• パスワードの値は決して返されません。 --redact を指定すると、ページの読み取り結果からトークン、API キー、JWT が取り除かれます。
• 監査ログ：すべての呼び出しについて、URL、許可／拒否の判定、所要時間、返されたバイト数が記録されます。
• Chrome の最近のアクティビティ：ポップアップには直近 5 件のアクティビティ行が表示されます（タブを開く／閉じる操作の組み合わせは 1 行にまとまります）。設定では、結果のフィルターを使って最大 100 件を確認できます。このセッション履歴にはウェブサイト名とアプリキーが含まれますが、ページのテキスト、入力した値、完全な URL は含まれません。
• アクセスを停止：ポップアップまたは設定から、すべてのアプリを切断できます。停止状態は再起動後も維持されます。接続を再開するには、アプリごとに新たな承認が必要です。すでに実行中のコマンドは完了する場合があり、完了した操作を元に戻すことはできません。
• 表示中のタブには干渉しません：エージェントはバックグラウンドで独自のタブを開いて作業するため、表示中のページが移動、クリックされたり、フォーカスを奪われたりすることはありません。batch を使うと、1 回の呼び出しで複数のページをまとめて読み取れます。
• 複数の Chrome プロファイル：仕事用と個人用のプロファイルに拡張機能を読み込み、profile_use で切り替えられます。
• auth_check：セッションの有効期限が切れた場合、エージェントには分かりにくいタイムアウトではなく [AUTH_REQUIRED] シグナルが返されます。そのため、処理を停止して再ログインを求めることができます。MCP Browser Extension が認証情報を保持したり、代わりにログインしたりすることはありません。

セットアップは 2 つの要素で構成されます。MCP サーバー（下記の npx）と拡張機能です。拡張機能は Chrome ウェブストアからインストール するか、サーバーが展開したフォルダーから読み込めます。

クイックスタート

1 回貼り付けるだけですぐに利用開始

これを AI エージェント（Claude Code、Cursor、Windsurf などの MCP 対応ツール）に渡すと、サーバーをインストールし、クライアントに接続して、拡張機能のインストール、メールアドレスの確認、Chrome とのペアリングを案内します。

Set up MCP Browser Extension on this machine by fetching and following
https://raw.githubusercontent.com/Mehmoodqureshi/mcp-browser-extension/main/SETUP.md
exactly, step by step. Work autonomously and verify each step.

エージェントを実行する前に内容を確認したい場合は、SETUP.md をご覧ください。エージェントが実行する手順がそのまま記載されています。手動での手順は以下のとおりです。

1. MCP サーバーを登録する：ホストに登録します。

claude mcp add mcp-browser-extension -s user -- \
  npx -y mcp-browser-extension@latest \
  --allow-domain example.com --enable-mutations --persist-token

{
  "mcpServers": {
    "mcp-browser-extension": {
      "command": "npx",
      "args": ["-y", "mcp-browser-extension@latest",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}

デフォルトではすべてがすべて拒否（ドメインなし、eval なし、変更なし）です。--allow-domain <glob>（繰り返し指定可能）、--enable-mutations、--enable-downloads、--enable-uploads、または --unsafe-enable-eval で、必要なものだけを許可してください。すべてのサイトへのアクセスはサポートされていません。Chrome 拡張機能のポップアップで、名前を指定してウェブサイトを承認してください。

メール認証はデフォルトで有効です。信頼できるローカルの無人セットアップでは、--no-email-verification（または MCP_BROWSER_EXTENSION_EMAIL_VERIFICATION=0 の設定）で無効にできます。これによりメール入力のプロンプトと Firebase アクセスサービスが省略され、メールアドレスやデバイス許可がそこに送信されなくなります。ローカルの MCP クライアントは、拡張機能を使用する前に Chrome 内で引き続き承認が必要であり、設定済みのドメインおよび機能ポリシーの範囲内で動作します。このローカルサーバーを起動または利用できるすべてのプロセスを、信頼できるものとして扱ってください。このオプションは --tunnel と併用できず、テレメトリや npm の更新チェックも無効になりません。

--enable-uploads を指定すると、upload_file（ページのファイル <input> にローカルファイルを設定する機能）が許可されます。ローカルファイルをページに送信すると情報漏えいのリスクがあるため、デフォルトでは無効です。また、送信先ドメインの許可リストによる制限も適用されます。--uploads-dir <path> と組み合わせると、そのディレクトリ内のファイルにアップロードを制限できます（.. によるディレクトリ遡りはブロックされます）。無人で使用する場合は、この設定を強く推奨します。

再起動後もトランスポートのペアリングを維持します。 上記の両方の例には --persist-token が含まれており、これによって再起動後もペアリングが維持されます。次に説明する、より厳格なデフォルトを使用する場合は、このオプションを省略してください。

--persist-token を指定しない場合、起動のたびに新しいトークンが発行されます（セキュアなデフォルト設定）。そのため、再起動のたびに拡張機能とのペアリングが必要です。指定した場合、トークンは ~/.mcp-browser-extension/token にアクセス許可 0600 で保存され、再利用されます。拡張機能のキープアライブが自動再接続するため、手動操作は不要です。MCP_BROWSER_EXTENSION_TOKEN を指定するとトークンを固定できます（ディスクには保存されません）。このトランスポートのペアリングによってアプリへのアクセスが許可されるわけではありません。新しいアプリセッションごとに個別のキーが必要で、Chrome での承認も必要です。

2. 拡張機能をインストールします — 必須です。拡張機能がなければ、サーバーは何も操作できません。

Chrome ウェブストアから MCP Browser Extension をインストール。 ワンクリックでインストールでき、デベロッパーモードは不要です。また、Chrome が自動的に最新の状態に保ちます。この方法でインストールしてください。

3. メールアドレスを確認します。 MCP クライアントで、エージェントに chrome_status を呼び出すよう依頼します。最初のブラウザツール呼び出し時に、クライアントにメール入力のプロンプトが表示されます。アクセスできるメールアドレスを入力し、そのアドレスに届いたサインインリンクを開いて、このデバイスを確認をクリックしてください。待機中のツールにメール認証済みと表示され、処理が続行されます。

ツールが ACCESS_PENDING を返した場合は、エージェントにもう一度 chrome_status を呼び出すよう依頼し、同じリンクの確認を続けてください。新しいメールや認証コードは必要ありません。

クライアントがプロンプトを抑止する場合（たとえば YOLO／バイパスモードの場合）、MCP のエリシテーションに対応していない場合、またはダイアログが閉じられた場合、サーバーはブラウザで一時的なローカル認証フォームを自動的に開きます。ツールはリンクとともに ACCESS_INPUT_REQUIRED も返すため、必要に応じて MCP サーバーを実行しているコンピューター上で自分でリンクを開けます。ブラウザフォームにメールアドレスを入力し、受信トレイに届いたサインインリンクを開いてください。このデバイスを確認をクリックしてから、chrome_status を呼び出して続行します。 ローカルフォームの有効期限は 10 分です。新しいフォームを表示するには、ツールをもう一度呼び出してください。フォームを開いてもメールは送信されません。また、メールリンクとデバイス許可が認証されるまでアクセスはブロックされたままです。拡張機能をインストールしただけではアクセスは有効になりません。 4. Chrome がまだペアリングされていない場合は、Connect をクリックします。 新規インストールすると、拡張機能の設定が開き、 Connect ボタンが表示されます（ツールバーのポップアップにもあります）。これをクリックし、Chrome から求められる権限を 1 つ許可すると、ペアリングが完了します。サーバーは起動するたびに Chrome に小さなヘルパーを登録し、ボタンからそのヘルパーにポートとトークンを問い合わせます。このヘルパーと通信できるのは、この拡張機能だけです。サーバーのトークンが変更されても、拡張機能が新しいトークンを自動で取得します。コピーや貼り付けは不要です。

5. Chrome でアプリの接続を承認します。 chrome_status を実行し、拡張機能のポップアップにある App connections セクションを開きます。キーのフィンガープリントがツールの結果に表示されたものと一致することを確認し、Approve for 8 hours をクリックします。アプリ名はアプリから提供されます。キーは、この特定のセッションを識別します。承認後、ツールを再試行します。クライアントがプロンプトを表示しない場合でも、保留中のリクエストは疑問符のバッジとポップアップに表示されます。ポップアップまたは設定から、接続の承認、拒否、取り消し、復元を直接行えます。

各アプリセッションには固有の署名キーがあり、そのキーはサーバーセッションのメモリ内にのみ保持されます。承認は、この Chrome プロファイルに対して 8 時間有効です。アプリの MCP 接続を再起動すると新しいキーが作成され、再度承認が必要になります。Remove access を実行すると、そのキーからの以降のコマンドはブロックされます。すでに実行中のアクションは完了する場合があります。YOLO、権限バイパスモード、--no-email-verification では、この拡張機能によるチェックをスキップできません。

6. 必要なウェブサイトを許可します。 ポップアップにウェブサイトへのアクセスリクエストが表示されます。Allow をクリックし、表示された場合は Chrome のウェブサイト権限プロンプトを承認します。この一連の操作により、指定したウェブサイトが Chrome とサーバーの許可リストの両方で許可されます。ウェブサイトを許可すると、承認済みのアプリは、そのウェブサイトで情報を読み取り、メッセージの送信、情報の削除、購入などの操作を実行できるようになります。これらの操作には、設定済みのツール権限が適用されます。操作ごとに拡張機能で個別に承認する必要はありません。ウェブサイトへのアクセス許可は、削除するまで保持され、承認済みのアプリセッション間で共有されます。ただし、各アプリには引き続き、有効期限内の個別の接続承認が必要です。ウェブサイトを削除すると、その Chrome 権限も削除されます。既存のサーバーフラグでは Chrome へのアクセスは許可されません。また、アップグレード後にウェブサイトの再承認が求められる場合があります。

Cookie とダウンロードは、必要に応じて Extra permissions から個別に許可します。これらは初期状態では無効で、各ボタンから権限を削除することもできます。ダウンロードはブラウザーの Cookie を使わずに取得され、リダイレクトは拒否されます。また、ファイルサイズは 50 MiB までに制限されます。サインイン済みのブラウザーセッションやリダイレクトが必要なリンクは、機能しない場合があります。プロキシ認証と IP ルックアップは、設定から権限をリクエストします。Chrome では debugger や proxy を任意の権限にできないため、これらは引き続き必須です。また、debugger コマンドは実行前にウェブサイトの権限を確認します。

クライアント承認を使用する前に、拡張機能とサーバーの両方を更新してください。古い拡張機能では承認を強制できず、更新済みのサーバーは拡張機能が更新されるまでブラウザーコマンドを拒否します。クライアント承認の詳細を参照してください。

バッジの場所： バッジは Chrome のツールバーにある拡張機能アイコンに表示され、chrome://extensions ページには表示されません。Chrome では、新しい拡張機能はアドレスバーの右側にあるパズルピースボタンの裏に隠れています。そのボタンをクリックして MCP Browser Extension を探し、横にあるピンを一度クリックしてください。アイコンがツールバーに固定されます。アイコンにカーソルを合わせると、状態が文字で表示されます。

手動での代替手順（ヘルパーが --no-native-host で無効になっている場合、または Connect で問題が報告される場合）：npx -y mcp-browser-extension@latest --print-pairing を実行し、拡張機能の Settings を開いて、~/.mcp-browser-extension/handshake.json にある port と token を貼り付けます。

Chrome の再起動後に拡張機能が見つからない

読み取り専用の診断を実行すると、実際のインストールの種類、不足ファイル、Chrome の無効化理由、競合する拡張機能の登録状況を確認できます。

npx -y mcp-browser-extension@latest extension doctor

古い展開版では、更新によって manifest に Web Store の公開鍵が追加された際に、新しい ID が割り当てられることがありました。その後 Chrome は、1 つのフォルダーに対して 2 つの ID を保持し、次回の起動時にそのフォルダーを読み込まなくなりました。現在は更新時に既存の ID が維持されます。この特定の競合がすでに発生しているインストールでは、次の手順を実行してください。

npx -y mcp-browser-extension@latest extension repair
# Review the preview, fully quit Chrome and other Chromium browsers, then:
npx -y mcp-browser-extension@latest extension repair --apply

修復では、元の設定を ~/.mcp-browser-extension/extension-repair-backups/ にバックアップし、古いことが確認された登録情報だけを削除して、現在の拡張機能と保存済みの設定を維持します。Chromium ブラウザーの実行中は書き込みを行いません。修復後に Chrome を再度開いてください。カスタムのブラウザーデータ保存場所には --user-data-dir <directory> を使用するか、診断レポートには extension doctor --json を使用してください。レポートには拡張機能のパスと登録状況が含まれますが、閲覧履歴、Cookie、ペアリングトークンは含まれません。

一致する古い ID の競合がない Web Store インストールには変更を加えません。診断でファイルの不足、無効化されたストア版、または登録がないことが見つかった場合は、個別に原因を調べる必要があります。このコマンドは原因を決めつけたり、ブラウザープロファイルをリセットしたりしません。展開版からストア版に移行する場合は、先に展開版を削除してから、ストアからインストールしてください。

複数のセッションを実行する

すべての MCP ホストセッション（Claude の各ターミナル、タブ、ウィンドウ）は、それぞれ独自の MCP Browser Extension サーバーを起動し、すべてが同時に Chrome を共有します。最初に起動したセッションが ブリッジポートと拡張機能の接続を確保し、ハブになります。後から起動した各セッションは、 稼働中の MCP Browser Extension サーバーが確保しているポートを見つけ、ピアとして参加します。ツール 呼び出しはハブを介して同じブラウザーに中継されるため、すべてのセッションが 並行して動作し続けます。接続が切断されることはありません。

ハブのセッションが終了すると、ピアがポートの確保を競い、そのうちの 1 つが引き継ぎます （トークンはそのままなので、拡張機能は数秒以内に自動で再ペアリングします）。 残りのピアは新しいハブに参加します。その時点で実行中だった呼び出しは 一度 EXTENSION_DISCONNECTED で失敗し、安全に再実行できる場合は自動的に再試行されます。

ピアは、0600 のハンドシェイクファイルにあるペアリングトークンを使ってローカルトランスポートを 認証します。ただし、そのトークンだけではブラウザーコマンドを実行できません。各セッションは、 Chrome 内で承認されたキーを使って自身のコマンドに署名する必要があります。ポートを共有できないほど 古いサーバーは、従来どおり置き換えられます。まず MCP Browser Extension サーバーであることを検証し、その後停止します。 MCP Browser Extension サーバーであることが検証されていないものには一切触れません。別のプログラムがポートを 使用している場合は、そのことを報告しますが、停止はしません。

セッションは 1 つのブラウザーを共有するため、タブも共有します。同じタブを 2 つのセッションが 同時に操作すると、互いの操作が干渉します。各セッションに独自のタブ（tab_new）を用意するか、 独自の Chrome プロファイル（下記）を使用してください。

各セッションは、複数のブラウザーを同時に操作することもできます。各 Chrome プロファイルに拡張機能を 読み込むと、すべてが同じサーバーにペアリングされ、それぞれのプロファイル名で認識されます。 ツールはアクティブなプロファイルに対して動作します。起動時に --profile <name> を使うか、 実行時に profile_use ツールを使って選択してください。

名前は自動的に付けられます。Chrome は拡張機能がどのプロファイルで実行されているかを通知しないため、 各インストールはランダムな ID を保持し、サーバーが名前を付けます。最初のブラウザーは default、次は profile-2、その次は profile-3 のようになります。名前は ~/.mcp-browser-extension/profiles.json に保存されるため、ブラウザーを再起動しても名前は保持されます。 chrome_status は、ペアリング済みのブラウザーをすべて（ヒントとしてアクティブなタブも）一覧表示し、 profile_rename でわかりやすい名前（profile-2 → work）を付けられます。 自分で名前を固定するには、拡張機能の Options → Profile に名前を入力してください。入力した名前が常に優先されます。

--port を指定しない場合、各サーバーは一時ポートにバインドされるため、競合は発生しません。ただし、 起動するたびにポートが変わるため、毎回拡張機能を再ペアリングする必要があります。一度だけペアリングする構成にするには、 --port と --persist-token を固定してください。

Windows

WSL2 は不要で、Windows ネイティブ環境で動作します。ただし、設定を 1 つ変更する必要があります。 Windows では npx はバッチシムの npx.cmd です。MCP ホストはシェルを介さずにサーバーを起動するため、.cmd を実行できません。そのため、"command": "npx" では起動に失敗します。cmd /c でラップしてください。

{
  "mcpServers": {
    "mcp-browser-extension": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-browser-extension@latest",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}

または、Claude Code から実行します：claude mcp add mcp-browser-extension -- cmd /c npx -y mcp-browser-extension@latest --allow-domain example.com

通常の使用では、上記の説明に従って Chrome Web Store から拡張機能をインストールし、Connect をクリックしてください。通常の Windows セットアップでは、Load unpacked を使用しないでください。展開した開発者用ビルドは Store 版と同じ拡張機能 ID を使用するため、読み込むと Store 版が置き換わる可能性があり、その場合 Chrome が Store 以外のコピーを無効にすることがあります。mcp-browser-extension を開発している場合は、別の Chrome プロファイルで %USERPROFILE%\mcp-browser-extension を読み込んでください。

ツールには、タブ、ナビゲーション、操作（click／type／press／hover／scroll／select_option）、読み取り（get_text／get_html／screenshot／eval／wait_for）、アクセシビリティの snapshot（モデルが CSS セレクターを推測する代わりに対象を指定できる、安定した ref を持つインタラクティブ要素）、セッションへのアクセス（get_cookies／storage）、ヘルパー（extract_links／read_as_markdown／fill_form／download_file／upload_file）、および chrome_status が含まれます。upload_file は OS のダイアログを使わず、ローカルファイルを <input> に設定します（--enable-uploads が必要です）。

click／type は、実際の OS レベルの入力を行う trusted: true を受け付けます（React／Vue の制御された入力で動作します）。操作時には、対象が表示されるまで自動的に待機します。

どこからでも使用 — --tunnel

claude.ai、Claude モバイルアプリ、ChatGPT、別のマシン上の Claude Code、またはサーバー上で実行中のエージェントから、手元の Chrome を操作できます。

brew install cloudflared            # once (Windows: winget install --id Cloudflare.cloudflared)
npx -y mcp-browser-extension@latest --tunnel --allow-domain example.com --enable-mutations

https://<random>.trycloudflare.com/mcp/<key> のようなコネクター URL が出力されます。

• claude.ai／Claude モバイル： Settings > Connectors > Add custom connector を開き、URL を貼り付けます。
• ChatGPT（ウェブ）： Plugins > Add > Add custom MCP server を開きます。Server URL を選択し、完全なコネクター URL（/mcp/<key> を含む）を貼り付けて、No authentication を選択します。個人用プラグインを作成してインストールし、新しいチャットで @ を使って選択します。トンネルは起動したままにしてください。
• 別の場所の Claude Code／エージェント： <url>/mcp と Authorization: Bearer <key> を使用します。正確な claude mcp add コマンドも出力されます。

キー（ランダムな 32 バイトで、~/.mcp-browser-extension/remote-key に保存されます）はすべてのリクエストを保護します。キーが間違っている場合や欠けている場合は、本文のない 404 が返されます。URL を持っている人は誰でも、許可されたサイト内でブラウザーを操作できるため、URL は非公開にし、許可リストを厳格に保ってください。--rotate-remote-key を実行すると、すべてのクライアントが切断されます。クイックトンネルの URL は起動のたびに変わります。--http のみを指定すると 127.0.0.1:38018（--http-port）で待ち受けるため、自分のトンネル（ngrok、Tailscale Funnel、リバースプロキシ）を利用できます。サーバーは Ctrl-C を押すまで実行されます。

Chrome プロファイルごとのプロキシ — proxy_status

Chrome のプロキシ設定はタブ単位ではなくプロファイル全体に適用されるため、IP ごとに Chrome プロファイルを用意してください。そのプロファイルで拡張機能の Settings ページからプロキシを設定し、そこでプロファイル名を付け、profile_use で切り替えます。プロキシが停止している場合、実際の IP にフォールバックせず、ページの読み込みに失敗します。proxy_status は出口 IP と国を報告します。エージェントはプロキシを変更したり、そのパスワードを読み取ったりできません。

複数のタブを同時に操作する — batch

batch は複数のツール呼び出しを 1 回の リクエストで実行します。parallel（デフォルト）または serial（任意の stopOnError を指定可能）を選べます。各サブ操作には、直接呼び出す場合と同じポリシーゲート、レート制限、エラー処理が適用されます（バイパスやネストはできません）。タブにまたがって処理を振り分けるには、次のように使います。

// open three product pages (background, so they don't fight for focus)…
{ "name": "batch", "arguments": { "ops": [
  { "tool": "tab_new", "args": { "url": "https://a.example/p" } },
  { "tool": "tab_new", "args": { "url": "https://b.example/p" } },
  { "tool": "tab_new", "args": { "url": "https://c.example/p" } }
]}}

// …then read them all at once (wall-clock ≈ the slowest one, not the sum)
{ "name": "batch", "arguments": { "ops": [
  { "tool": "get_text", "args": { "tabId": "<a tabId>" } },
  { "tool": "get_text", "args": { "tabId": "<b tabId>" } },
  { "tool": "get_text", "args": { "tabId": "<c tabId>" } }
]}}

parallel モードでは、タブを対象とする操作に明示的な tabId の指定が必要です。同時実行中にアクティブなタブをデフォルトで使うのは安全ではないため、誤ったタブにひそかに振り分けられるのではなく、拒否されます（tab_new、tabs_list、chrome_status は対象外です）。

エージェントはあなたのタブではなく、自分のタブで作業します。 tab_new はバックグラウンドでタブを開き、そのタブがエージェントのタブになります。tabId を指定しない呼び出しは、そのタブに対して実行されます。まだ自分のタブがない状態で navigate を実行すると、あなたのページを置き換えるのではなく、新しいタブを開きます。また、tab_new が再利用するのは自分で開いた空のタブのみで、あなたの「新しいタブ」ページは再利用しません。エージェントが何も開く前は、読み取りの対象はあなたのアクティブなタブなので、「このページを要約して」という指示はそのまま使えます。あなたのページを操作するには、エージェントが tabs_list から取得した tabId を指定します。タブを前面に表示するには、active: true を指定します。

iframe とシャドウルートへのアクセス

「一致するはず」のセレクターが一致しない場合、ほとんどの場合、その要素はセレクターが到達できない場所にあります。たとえば、<iframe>（決済ウィジェット、OAuth 同意画面、埋め込みエディター）や、ウェブコンポーネントのシャドウルートの内部です。

シャドウルートには自動的に対応します。すべてのセレクターと ref が、オープンなシャドウルートを通して解決されるため、snapshot に表示されるものはすべてクリックできます（以前は、シャドウルートをたどる snapshot には表示されても、操作からは到達できない要素がありました）。

フレームへのアクセスは、アクセスするかどうかを選択できるよう、デフォルトでは無効になっています。

frames_list {}                                  // what frames exist, and their URLs
click { "selector": "#pay", "allFrames": true } // find it in whichever frame has it
get_text { "frameId": 7 }                       // pin one frame

各フレーム内で処理を実行する前に、そのフレーム固有の URL に対して認可を確認します。そのため、許可リストにあるページにサードパーティーの iframe が埋め込まれていても、そのサードパーティーの内容を読み取る手段にはなりません。オリジンが許可リストにないフレームはスキップされます。

ページが壊れた理由を確認する — console_logs、network_log、dialogs

DOM を読み取れば、ページが失敗した後の状態はわかりますが、失敗した理由まではわかりません。--enable-observers を指定すると、ページ内フックがコンソール出力、捕捉されなかったエラー、fetch／XMLHttpRequest の通信を記録し、ネイティブダイアログを捕捉します。

console_logs { "level": "exception" }    // the uncaught error behind a broken page
network_log  { "failedOnly": true }      // the 500 behind the blank screen
dialogs      { "policy": "accept" }      // answer confirm() with true from here on

これはデフォルトでは無効です。意図的にそうしています。このフックは、実際に使用しているブラウザーで許可リストにあるすべてのページの console、fetch、XMLHttpRequest、ダイアログ関数にパッチを適用します。有効にすると、許可リストにあるドメインに限り、document_start のタイミングで登録されるため、ページ読み込み時のエラーも捕捉できます。ツール呼び出しで読み取られるまでは、記録された内容がページ外に出ることはありません。読み取りには、他のページの読み取りと同じゲートが適用されます。

ダイアログの捕捉は、単なる観測ではなく問題の解決にもなります。alert／confirm／beforeunload はレンダラーをブロックするため、ダイアログを開いたクリックによって、コマンドがタイムアウトするまで注入されたスクリプトがすべて停止し、原因を特定できないまま TIMEOUT が報告されることがありました。オブザーバーを有効にすると、ダイアログに応答し（デフォルトでは dismiss。confirm → false、prompt → null）、その内容を記録します。

network_log が確認できる内容： ページのコードが行うリクエスト、つまりメソッド、URL、ステータス、所要時間を含む fetch と XMLHttpRequest のほか、要求された場合はリソースのタイミング情報（スクリプト、画像、スタイル）です。ドキュメントのリクエスト、リダイレクト、ヘッダーは対象外です。これは、ブラウザーでデバッガーセッションを開いたままにしないための代償です。

変更された部分だけを取得する — snapshot { diff: true }

スナップショットは、このツール群の中で最もコストの高い読み取りです。また、スナップショットを最も頻繁に使うループ（スナップショット → クリック → スナップショット）では、ほとんど同じページを毎回再送信しています。代わりに差分を取得します。

snapshot { "diff": true }                       // added / removed / changed only
click { "selector": "#save", "snapshotAfter": true }   // what the click changed

スナップショット間のノードは、ref ではなく、ロールとアクセシブル名で照合されます。ref はスナップショットごとにドキュメント順で振り直されるため、それを使って差分を取ると、その上に何かが現れただけで、変化していないボタンまで削除されて再追加されたと報告されてしまいます。

ページを記録して、後から変更を確認する — page_watch

名前付きのアクセシビリティチェックポイントを保存し、後のセッションで現在のページと比較します。チェックポイントはアクティブな Chrome プロファイル内に保存されるため、仕事用と個人用のブラウザー ID は分離されます。

page_watch { "action": "create", "name": "Vendor pricing" }
page_watch { "action": "compare", "watchId": "watch_…" }
page_watch { "action": "list" }
page_watch { "action": "delete", "watchId": "watch_…" }

結果には、追加、削除、変更されたコントロールが表示されます。アクセシビリティラベルとコントロールの状態を保存し、URL のクエリ文字列を削除し、設定された墨消しを適用します。また、入力中のフォーム値を保存することはありません。チェックポイントの作成や比較には、引き続きページのドメインを許可する必要があります。

ロールと名前によるターゲット指定

アクションには CSS セレクターの代わりにロケーターを指定できるため、ref を知るためだけに先にスナップショットを取得する必要はありません。

click { "role": "button", "name": "Sign in" }
type  { "role": "textbox", "name": "Email", "text": "[email protected]" }

解決処理はサーバー側で行われ、推測はしません。ロケーターが曖昧な場合は、最初の候補に対して実行するのではなく、候補を一覧表示して失敗します（選択するには nth を渡します）。

セッションの有効期限が切れましたか？ — auth_check と failOnAuthWall

サインイン済みの Chrome を再利用すればログイン手順を省略できますが、実行中にセッション Cookie の有効期限が切れることがあります。明確なシグナルがないと、次の手順は SELECTOR_NOT_FOUND または TIMEOUT として失敗し、実際には認証エラーだったにもかかわらず、評価ハーネスは実行をエージェントの失敗として採点します。現在、すべての snapshot に、ページがサインイン画面のように見える場合の authWall 判定が含まれます。また、専用の検査ツールも用意されています。

auth_check {}                                   // { authRequired, confidence, signals }
auth_check { "failOnAuthWall": true }           // [AUTH_REQUIRED] error instead
navigate  { "url": "https://app.example.com/dashboard", "failOnAuthWall": true }
snapshot  { "failOnAuthWall": true }

ハーネスでは、呼び出しごとに設定するのではなく、一度だけ設定します。

npx -y mcp-browser-extension@latest --allow-domain app.example.com --enable-mutations --fail-on-auth-wall

このフラグを有効にすると、タブを移動させる可能性のある各手順（navigate、click、type、select_option、press、fill_form、back、forward、reload）で、移動先のページを確認します。移動先がサインイン画面の場合は [AUTH_REQUIRED] で失敗します。また、そのようなページでタイムアウトした wait_for は、[TIMEOUT] ではなく [AUTH_REQUIRED] を報告します。ガード付きの各手順では、スナップショットのラウンドトリップが 1 回余分に必要です。フラグが無効の場合、追加コストはありません。ハーネスは [AUTH_REQUIRED] を受け取ったら処理を一時停止し、同じ Chrome で人間に再度サインインしてもらってから、その手順を再試行します。MCP Browser Extension は、設計上、認証情報を保持せず、自動的に再認証することもありません。

検出では、スナップショットにすでに含まれている情報だけを読み取ります。対象は URL（サインイン用のルートや、accounts.google.com、login.microsoftonline.com、Okta、Auth0 などの ID プロバイダーのホスト）、タイトル、パスワードフィールド、サインイン用コントロールです。high の信頼度には、パスワードフィールドとサインインボタンなど、独立した手がかりが 2 つ必要です。パスワードフィールドだけの場合や、単独の /auth/... URL の場合は medium です。通常のページにある「サインイン」リンクは判定対象になりません。failOnAuthWall が作動するのは high の場合だけなので、ハーネスは [AUTH_REQUIRED] を他のすべての失敗と別に分類できます。また、「現在のパスワード」フィールドがある設定ページでは処理を続行します。

印刷 — print_pdf

print_pdf { "landscape": true }

Chrome 独自の印刷パイプラインでレンダリングし、タスクの results/ ディレクトリに保存して、パスとサイズを返します。PDF の内容そのものは返されません。PDF は数メガバイトにもなるため、モデルが読み取れない Base64 を返すことになるからです。

1 回のターンにかかるコストを削減する — --tools

接続する MCP サーバーは、何かを要求する前からコンテキストを消費します。ホストはすべてのターンで、ツールカタログ全体をモデルに送信します。MCP Browser Extension の 43 個のツールは 28 KB の JSON Schema で、毎回約 7.1k トークンを消費します。

多くの実行で必要なのは、そのうちの一部です。--tools を使うと、それらだけを公開できます。

npx -y mcp-browser-extension@latest \
  --allow-domain app.example.com --enable-mutations \
  --tools tabs_list,tab_new,navigate,snapshot,click,type,get_text

公開する範囲は6.0 KB、約 1.5k トークンで、完全なカタログから 78% 削減されます。PDF の印刷もファイルのアップロードもしない実行に適しています。

• カンマ区切りで指定でき、複数回指定できます：--tools navigate,get_text --tools click。
• 指定から外したツールは tools/list から隠され、呼び出されても拒否されます。そのツールを指定した batch 操作も、不明なツールと同様に失敗します。ツールを隠すことは表示フィルターではなく、実際の制限です。ただし、ポリシーゲートの代わりにはなりません。--tools eval を指定しただけでは、--unsafe-enable-eval がなければ何も起きません。
• 不明な名前を指定すると起動時に失敗し、カタログが表示されます。そのため、タイプミスによって click がひっそり公開対象から外れることはありません。
• mcp-browser-extension --help を実行すると、選択用に 43 個の名前を含む完全なカタログが表示されます。

ステータス

v0.5.0 — 安全な複数タブの並行処理。 batch ファンアウトツールを追加し、タブの並列自動操作を競合状態なく実行できるようにしました（明示的な tabId ガード、タブごとの chrome.debugger の直列化、競合のない tab_new）。また、chrome.debugger を使ったスクリーンショットの取得（フォーカスを奪わずに特定のタブを指定でき、真の全ページキャプチャと要素キャプチャにも対応）と、新しく開いたタブをデフォルトでフォーカスする機能を追加しました。自動テスト111件と、条件付きで実行する拡張機能の画面表示スモークテスト。

v0.2.0 — 6つすべてのビルドフェーズが完了し、正常に動作しています。エンドツーエンドで動作します： npx mcp-browser-extension ⇄ ブリッジ ⇄ 拡張機能 ⇄ 実際の Chrome。Playwright CDP フォールバックにも対応しています。v0.2では、アクセシビリティ対応の snapshot と要素参照、自動待機、Cookie／ストレージ／select_option、信頼された入力（chrome.debugger）、ツールバーのステータスバッジ、安定したペアリングトークン（--persist-token）を追加しました。

• フェーズ 0 — コントラクトと骨組み： shared/protocol.ts（ワイヤーコントラクト）、 src/executor/types.ts（Executor インターフェース）、src/security/policy.ts （デフォルト拒否ポリシー＋機能ゲート）、src/config.ts（CLI／環境変数／ポリシー 解決）、ビルド＋テストハーネス。
• フェーズ 1 — MCP サーバー＋StubExecutor： mcp/server.ts（標準出力を汚さない stdio）、mcp/tools.ts（28ツールのカタログ＋例外を送出しないディスパッチ＋ ドリフトチェック）、バリデーター／エンベロープ／ヘルパー、ExecutorManager＋ StubExecutor、cli.ts。今日から MCP ホストの接続先を node dist/src/cli.js にできます。
• フェーズ 2 — WebSocket ブリッジ＋認証： bridge/server.ts（ループバック WS、 hello-token ゲート、welcome／unauthorized、接続の置き換え）、bridge/auth.ts （起動ごとの256ビットトークン、アトミックな0600ハンドシェイク、SHA-256 timingSafeEqual）、bridge/connection.ts（ID相関、メソッド対応のタイムアウト、 バックプレッシャー、切断時の全リクエスト拒否、ハートビート）。
• フェーズ 3 — ExtensionExecutor＋CdpExecutor＋選択： executor/extension-executor.ts（ブリッジ経由の Executor）、 executor/cdp-executor.ts（Playwright の接続／起動＋ロック復旧＋ タブ解決）、executor/select.ts（ping に応答する場合は拡張機能、それ以外は CDP）。CLI がブリッジを起動し、0600のハンドシェイクを書き込み、 実際のバックエンドを提供するようになりました。playwright を追加。
• フェーズ 4 — MV3 拡張機能： extension/ — manifest.json、 sw/ws-client.ts（接続＋hello／welcome＋pong）、sw/executor.ts （chrome.scripting／chrome.tabs のコマンド実装）、sw/router.ts（例外を送出しない 処理＋ドリフト）、sw/background.ts（トップレベルのリスナー＋25秒のキープアライブ／再接続）、 オプションページ（手動ペアリング）、esbuild によるビルド → extension-dist/。実際の --load-extension スモークテスト（ペアリング → 移動 → get_text）で検証済みです。 esbuild＋@types/chrome を追加。
• フェーズ 5 — ヘルパー、ダウンロード、HITL： 強化した download_file （shared/download.ts — パストラバーサル／危険な拡張子のサニタイズ＋サイズ上限、 両方のバックエンドに組み込み）、機能を強化した read_as_markdown、純粋で 単体テスト済みのゲート処理を備えたヒューマン・イン・ザ・ループのハーネス （hitl/ — npm run test:hitl [-- --include-mutating]）。自動テスト50件。
• フェーズ 6 — パッケージングとドキュメント： files ホワイトリスト（dist/src、 dist/shared、extension-dist、LICENSE、ブループリントを同梱し、ソース／テストは含めない）、 prepack ビルド、bin、クイックスタート＋.mcp.json のスニペット。tarball の インストールスモークテスト（npm pack → インストール → MCP tools/list）で検証済みです。

セキュリティポスチャ（デフォルト）

すべて拒否するセーフモード。 ポリシーを設定しない場合、ドメイン許可リストは空で、eval はオフ、ダウンロードはオフ、変更を加えるツールはオフです。明示的に有効にしてください：

mcp-browser-extension --allow-domain example.com --enable-mutations
mcp-browser-extension --policy ./policy.json          # see policy.example.json
mcp-browser-extension --enable-observers              # console/network/dialog capture (patches page globals)
mcp-browser-extension --redact                        # scrub secret-shaped strings out of page reads

再起動せずにサイトを許可する。 サイトが許可されていないため呼び出しが拒否されると、拡張機能のツールバーアイコンに ? が表示されます。クリックすると、ポップアップにブロックされたサイトと Allow ボタンが表示されます。また、現在表示しているサイトが許可されているかどうか（独自の Allow ボタン付き）や、許可済みのサイトも一覧表示されます。オプションページ（ポップアップの Settings）にも、ほかのサイトを許可するボックスがあります。サイトを許可すると、その Chrome を共有するすべてのセッションにすぐ反映され、~/.mcp-browser-extension/allowed-sites.json に保存されるため、再起動後も有効です。ここで許可したサイトはここから削除できます。--allow-domain で許可したサイトは、フラグが変更されるまで有効です。すべてに一致するパターンを指定してもアクセス権は付与されません。起動前に、古い設定から廃止された --unsafe-all-domains オプションを削除してください。エージェント自身がサイトを承認することはできません。MCP Browser Extension は拡張機能自身のページを読み取ったり操作したりしないためです。許可リストをフラグの指定どおりに固定するには、--no-site-grants を指定して実行してください。

返される内容にも制限が適用されます。 許可リストで、読み取り可能なページを決めます。ただし、そのページに何が含まれているかは制限しません。ログイン済みのページには、セッショントークンがスクリプトタグに、API キーが設定画面に表示されることがよくあります。

• Cookie の値はデフォルトで非表示です。 get_cookies は各 Cookie の名前、ドメイン、パス、フラグを返し、値は [hidden] に置き換えます。セッション Cookie があれば、パスワードなしでアカウントにアクセスできる場合があります。本当に必要なタスクでは、--enable-cookie-values を渡してください。
• パスワードフィールドの値は常に抑制されます — get_html では値が表示されず、snapshot ではフィールド自体は表示されるため入力できますが、secret: true のフラグが付けられ、値は含まれません。フラグもオプトインも不要です。あの文字列を見たい人はいません。
• --redact を指定すると、get_text、get_html、read_as_markdown、eval から、JWT、AWS／GitHub／Slack／Google のキー、Bearer ヘッダー、秘密鍵ブロックなど、秘密情報らしい文字列も削除されます。必要な情報にパターンが一致してしまうこともあるため、これはオプトイン方式です。--redact-pattern <regex> を指定すると独自のパターンを追加でき（--redact も暗黙的に有効になります）、無効なパターンは一致しないまま見過ごされず、起動時にエラーになります。
• 出力上限を適用する前に秘匿化を行うため、読み取り結果が途中で切り詰められても、全体を読み取った場合に隠される情報が漏れることはありません。

各呼び出しは、アクセスした URL、ポリシー判定（allowed／denied）、所要時間、返されたバイト数、削除された秘密情報の数とともに、タスクの history.jsonl に記録されます。そのため、「エージェントが自分のブラウザーで何をしたか」を後から確認できます。

起動ごとに生成される ~/.mcp-browser-extension/handshake.json 内の 256 ビットトークン（モード 0600）が、唯一の信頼境界です。このトークンが stdout／stderr に書き出されることはありません。POSIX では、書き込みのたびにモードを再検証し、ファイルがグループまたはその他のユーザーからアクセス可能な状態になった場合、サーバーはフェイルクローズします。Windows にはこのような権限ビットがありません。そこでの chmod は読み取り専用属性を切り替えるだけなので、このチェックは省略され、トークンの機密性は %USERPROFILE%\.mcp-browser-extension のユーザーごとの ACL に依存します。

更新

最新の状態を保つために、何かをする必要はありません。上記のセットアップ例では @latest を使用しています。それに加えて、インストール済みのコピー（npx またはグローバルインストール）は起動時に npm を確認します。新しいバージョンが公開されていれば、同じ引数でそのバージョンを起動するため、数か月前に書かれた MCP 設定でも最新リリースが実行されます。オフラインの場合、確認は 1.5 秒後に中断されます。また、git チェックアウトから実行されたコピーは自動更新されません。新しいサーバーは ~/mcp-browser-extension に展開済みの拡張機能も更新し、拡張機能は自動で再読み込みされます。Chrome ウェブストア版は通常どおり Chrome 経由で更新されます。--no-auto-update または MCP_BROWSER_EXTENSION_AUTO_UPDATE=0 を指定すると無効にできます。

テレメトリ

MCP Browser Extension の サーバー（拡張機能ではありません）は、匿名の使用統計を PostHog に送信します。これにより、プロジェクトではアクティブなインストール数、使用されているバージョンやプラットフォーム、最もよく失敗するツールを確認できます。初回実行時に通知が表示されます。

送信される情報：ランダムなインストール ID（~/.mcp-browser-extension/telemetry.json に保存）、サーバーのバージョン、OS、CPU アーキテクチャ、Node のメジャーバージョン、セッションがブリッジポートを所有しているか共有しているか、ペアリングされたブラウザーの数、ペアリングされた拡張機能のバージョンと、それがストア版か展開済みコピーかどうか、そしてツールごとの呼び出し数とエラーの件数およびエラーコードです。最初のバッチは最初のツール呼び出しから1分後に送信され、その後は10分ごとに送信されます。PostHog の MCP Analytics ビュー向けに、各ツール呼び出しは $mcp_tool_call イベントとしても送信されます。含まれる情報は、ツール名とそのグループ（読み取り、ナビゲーションなど）、実行時間、失敗したかどうかとエラーのコード、MCP クライアントの名前とバージョン（claude-code など）、MCP プロトコルのリビジョン、クライアントが独自のリクエストメタデータで指定した場合の AI モデル（Codex が指定します）、および30分間操作がないと変更されるランダムなセッション ID のみです。クライアントが接続すると、ハンドシェイクと提供されるツール名を記録するイベントが1つ送信されます。エージェントが送信または読み取る内容は送信されません。引数、結果、エラーメッセージ、意図は含まれません。15秒ごとにまとめて送信されます。起動から1分後に pair_check イベントが1つ送信され、ブラウザーがペアリングされたかどうかを示します。ペアリングされていない場合は、いくつかの固定された理由（no_extension、token_mismatch、version_mismatch、profile_mismatch）のうち該当するものが記録されるため、問題が発生した場所でセットアップを修正できます。

送信されることのない情報：URL、ドメイン、ツールの引数、ページの内容、スクリーンショット、Cookie、プロファイル名、トークン、ファイルパス、入力した内容は一切含まれません。イベントから個人を特定することはできず、GeoIP ルックアップは無効になっています。

ブラウザー拡張機能からは何も送信されません — 127.0.0.1 との通信のみを行います。

次のいずれかの方法で無効にできます。

MCP_BROWSER_EXTENSION_TELEMETRY=0     # or false / off
DO_NOT_TRACK=1
--no-telemetry             # server flag

詳細情報

詳細なドキュメント、各 MCP クライアント向けのセットアップガイド、セキュリティモデルは、ウェブサイトにあります：MCP Browser Extension のドキュメント。

• MCP ブラウザー拡張機能とは何か、どのような場合に必要か
• ログイン済みの Chrome で Claude を使う
• Claude Code にブラウザーへのアクセスを許可する
• MCP を使って Cursor に本物のブラウザーを提供する
• VS Code Copilot に実際の Chrome を使わせる
• AI エージェントでログインフローをエンドツーエンドでテストする
• ブラウザー MCP トンネル経由でリリースページを確認する
• Chrome DevTools MCP、Playwright MCP、MCP 拡張機能の比較
• 2026年のおすすめブラウザー MCP サーバー
• 他のブラウザー MCP サーバーとの比較

開発

npm install
npm run typecheck       # server/test sources
npm run typecheck:ext   # extension sources (@types/chrome)
npm run build:ext       # bundle the extension → extension-dist/
npm test                # builds, then runs node --test on dist/test
RUN_EXT_SMOKE=1 node --test dist/test/extension-smoke.test.js   # live, headed

拡張機能

Chrome ウェブストアでは MCP Browser Extension として公開されています。
拡張機能のバージョンは extension/ に変更があった場合のみ更新されるため、掲載されているビルドは npm パッケージより1リリース遅れている場合があります。接続時に両者で機能をすり合わせるため、古い拡張機能では機能が利用できなくなるだけで、動作が壊れることはありません。

通常の使用では、上記の Chrome ウェブストアからインストールしてください。以下はローカル開発専用です。Chrome ウェブストア版と同じ Chrome プロファイルに、この展開済みコピーを読み込まないでください。Windows では、Chrome によってウェブストア以外のビルドが無効化されることがあります。

extension/ をビルドすると（esbuild）、extension-dist/ が生成されます。chrome://extensions → Load unpacked → ~/mcp-browser-extension を選択して読み込みます。これは、サーバーが起動のたびに extension-dist/ から更新するミラーです（extension-dist/ を直接読み込むこともできます）。拡張機能は、サーバーがそのフォルダーに書き込む pairing.json から自身をペアリングします。~/.mcp-browser-extension/handshake.json の port と token を Options ページに貼り付ける方法は、フォールバックの場合にのみ使用します（パスを確認するには npx -y mcp-browser-extension@latest --print-pairing を実行してください）。

読み取り／操作には chrome.scripting／chrome.tabs を使用します — 「デバッグ中」バナーは表示されず、CSP に安全な読み取り（分離されたワールド）を行え、Playwright でテストできます。
chrome.debugger は、必要かつ有効な場合にのみ使用します。具体的には、trusted: true の入力（React／Vue の入力欄への実際の OS レベルのイベント）と screenshot（特定のタブをアクティブ化せずにキャプチャするため、並列の batch でも安全で、真の全ページキャプチャと要素キャプチャに対応）です。これらの操作では接続中にデバッグバナーが表示されます。最後の操作から1.5秒間セッションが維持されるため、連続して実行しても接続は1回で済みます。スクリーンショットはデフォルトで CSS ピクセルサイズの JPEG（品質70）です。変更するには format: "png"、quality、または scale を渡してください。