BrowserTools MCP

BrowserTools MCP

まだ 1.x をお使いの場合は、アップグレードしてください。 1.x はサポート対象外です。既知の重大な脆弱性（リモートコード実行、キャプチャしたデータへの認証なしアクセス）があり、これらは 2.0 で修正されましたが、1.x には修正が提供されません。SECURITY.md と MIGRATION.md をご覧ください。

AI コーディングエージェントにブラウザーを見せましょう。BrowserTools MCP は、実際に使用している Chrome セッション（すでにアプリにログインしているセッション）から、コンソール出力、ネットワークアクティビティ、スクリーンショット、Lighthouse 監査結果を、Cursor、Claude Code、Windsurf、Cline、Zed、Gemini CLI など、MCP 互換クライアントにストリーミングします。

バージョン 2.0 は全面的に書き直されています。 プロセスは 3 つから 1 つになり、認証なしでアクセスできるローカルサーバーはなくなりました。認証情報はブラウザーから送信される前に除去され、実際に動作するテストスイートも用意されています。1.x から移行する場合は、MIGRATION.md をお読みください。

---

CDP ベースのサーバーではなく、これを選ぶ理由

Chrome DevTools MCP や Playwright MCP などのツールは、新規の自動化ブラウザーを操作します。テストを書くには適していますが、実際に表示しているアプリをデバッグするには適していません。Chrome 136 以降、ブラウザーはログイン情報を保持しているデフォルトのプロファイルでのリモートデバッグを拒否するためです。そのため、デバッグを始める前に、一時的なプロファイルで認証状態を再現する必要があります。

BrowserTools は DevTools 拡張機能を通じて、すでに使用しているセッションに接続します。ログイン状態や現在表示しているページを維持したまま、エージェントが画面に表示されている内容を読み取ります。また、自動化を優先するサーバーでは取得できない、Lighthouse 相当のパフォーマンス、アクセシビリティ、SEO データも報告します。

インストール

必要なものは 2 つです。MCP サーバー（コマンド 1 つ）と Chrome 拡張機能です。

1. MCP クライアントをサーバーに接続する

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": ["-y", "@agentdeskai/browser-tools-mcp@latest"]
    }
  }
}

Windows でクライアントが npx を見つけられない場合は、"command": "cmd" と "args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"] を使用してください。

Node 22.19 以降が必要です。node --version で確認してください。nvm または asdf を使用している場合は、エディターが同じバージョンを引き継いでいることを確認してください。

2. Chrome 拡張機能を読み込む

1. このリポジトリをダウンロードまたはクローンします。
2. chrome://extensions を開き、デベロッパー モードをオンにします。
3. パッケージ化されていない拡張機能を読み込むを選択し、chrome-extension ディレクトリを指定します。

設定はこれで完了です。起動する 2 つ目のサーバーはありません。MCP サーバーがコネクター自体を実行します。

3. 使用する

調査したいページで Chrome DevTools（F12）を開きます。DevTools を開くとキャプチャが始まります。BrowserTools パネルは設定とステータスの確認にのみ使用します。その後、エージェントに 「コンソールにエラーがないか確認して」 や 「このページのアクセシビリティ監査を実行して」 などと指示してください。

動作しない場合は、npx @agentdeskai/browser-tools-mcp --doctor を実行してください。不足しているものを正確に報告します。

キャプチャの様子をリアルタイムで確認するには（新規インストールの確認に便利です）、--verbose を付けてコネクターを起動します。

npx @agentdeskai/browser-tools-server --verbose

· console error tab 42 Uncaught TypeError: total is not a function
· network 500 POST tab 42 https://myapp.local/api/pay (1310ms)

このオプションを付けない場合、コネクターは接続と切断のみを報告するため、正常に動作している状態と何も起きていない状態を見分けられません。

ツール

ツール	機能
getConsoleLogs	コンソール出力。キーワードで絞り込み、ページ分けできます
getConsoleErrors	エラーレベルの出力と未捕捉の例外
getNetworkLogs	ステータス、所要時間、本文を含む XHR/fetch リクエスト
getNetworkErrors	失敗したリクエストと 4xx/5xx のリクエストのみ
getSelectedElement	Elements パネルで選択されている要素
getPageInfo	ブラウザーで現在開いているページ
getConnectionStatus	拡張機能の接続状態とキャプチャ件数
listBrowserTabs	DevTools が開いているタブ。DevTools に接続された tabId で指定します
listTabs	chrome.tabs が返すタブ（開いているすべてのタブではありません）。chromeTabId で指定します
readTab	デバッガーを使わずに、chromeTabId の見出し、抜粋、スナップショットを取得します
navigateBrowser	DevTools に接続されたタブで、フォーカスを移さずに URL を読み込みます
navigateTab	listTabs のタブで、表示中のウィンドウ内でバックグラウンドから URL を読み込みます
softClick / softType	信頼されていないクリックまたは入力です。結果は worked または needs a real gesture です
takeScreenshot	画像として返されるスクリーンショットと、そのファイルパス
refreshBrowser	検査中のタブを再読み込みします
getBrowserStorage	localStorage、sessionStorage、Cookie（値へのアクセスは制限されています）
wipeLogs	クリーンな再現の前にキャプチャしたテレメトリーを消去します
runAccessibilityAudit	Lighthouse のアクセシビリティ監査
runPerformanceAudit	Core Web Vitals を含む Lighthouse のパフォーマンス監査
runSEOAudit	Lighthouse の SEO 監査
runBestPracticesAudit	Lighthouse のベストプラクティス監査

これらに加えて 3 つのプロンプト、debuggerMode、auditMode、nextjsSeoAudit が付属しており、すべてのツール一覧に静的なテキストが並ぶ代わりに、エージェントに体系的なワークフローを提供します。

すべてのツールで MCP 出力スキーマが宣言されているため、クライアントは解析が必要な文章ではなく構造化データを受け取れます。また、読み取り専用のツールにはその旨が注釈されているため、クライアントは安全に自動承認できます。

DevTools を使わないタブ

listTabs、readTab、navigateTab、softClick、softType は chrome.tabs と chrome.scripting を使用します。デバッガーを接続しないため、デバッグバナーは表示されず、タブをアクティブにしたりウィンドウにフォーカスしたりすることもありません。

chromeTabId は listTabs から取得します。ほかのツールで使う tabId は listBrowserTabs から取得します。これらは異なる ID 空間です。それぞれの ID は、その ID を発行したツールにのみ渡してください。

listTabs は、chrome.tabs が返すウィンドウ内のタブを報告します。ほかの Arc Space、Little Arc、ピン留めされたお気に入り、分割表示の相手側、スリープ中のタブは含まれない場合があります。シークレットモードは対象外です。開いているすべてのタブが含まれるわけではありません。Arc で計測されるまでは、バックグラウンドでの移動は表示中のウィンドウ内にとどまります。

ポップアップのスイッチをオンにする必要があります。ナビゲーションとソフト入力には、browser-tools-mcp の --allow-input、または browser-tools CLI の --allow-actions も必要です。ほかの入力と同じオリジン規則が適用されます。スリープ中のタブはその旨が報告され、再読み込みされません。ソフトアクションの結果は worked または needs a real gesture であり、失敗したアクションを成功したとは報告しません。

複数のタブを同時に扱う

DevTools が開いている各タブは個別に追跡されます。テレメトリーは生成元のタブに紐づけられ、保持期間もタブごとに設定されるため、頻繁に通信するページが、確認したいタブの履歴を押し出すことはありません。

ツールは現在のタブ、つまり最後に DevTools を開いたタブに対して動作します。接続が一度切れて再接続したタブがその位置を奪うことはありません。これまでは、これが原因でスクリーンショットに誤ったページが写ることがありました。すべての結果には、取得元の tabId と url に加えて otherTabs が含まれるため、誤ったタブに対する回答を見落とさずに済みます。特定のタブを対象にするには、listBrowserTabs を呼び出してその tabId を任意のツールに渡します。すべてのタブを対象に読み取るには、allTabs: true を渡してください。

大量のデータをコンテキストウィンドウに入れない

全履歴のペイロードはインライン化せず、MCP のリソースとして公開します。ツールはそれらへのリンクに resource_link を使用するため、エージェントは必要と判断したときにのみ取得します。

リソース	内容
browser-tools://console/{tabId|all}	各呼び出しの予算上限なしで、すべてのコンソールエントリを取得します
browser-tools://network/{tabId|all}	本文を含む、キャプチャしたすべてのリクエストを取得します
browser-tools://har/{tabId|all}	同じ通信を HAR 1.2 ファイルとして取得します
browser-tools://screenshot/{name}	以前にキャプチャしたスクリーンショットを取得します
browser-tools://audit/{reportId}	要約の元になった、Lighthouse の完全なレポートを取得します

読み取りが途中で打ち切られた場合、ログツールはリンクを追加します。ネットワークの読み取りでは常に HAR が提示されます。スクリーンショットには保存された画像へのリンクが常に付与されます。インライン化できないほど大きな画像を見るには、この方法を使う必要があります。直近 20 件の Lighthouse レポート全体は、スクリーンショットディレクトリの audits/ に保存されます。

レスポンスを小さく保つ

コンテキストウィンドウを使い切る主な原因はログのペイロードです。すべての読み取りツールは limit と offset を受け取り、ログツールはキーワードフィルターも受け取ります。

getConsoleErrors({ keywords: ["hydration"], limit: 20 })
getNetworkLogs({ urlKeywords: ["/api/"], bodyKeywords: ["quota"], limit: 10 })

結果は新しいものから順に返され、total と returned が常に併記されるため、エージェントは結果の一部しか見ていない場合に把握できます。

プライバシーとセキュリティ

このツールはブラウザーに表示されるものをすべてキャプチャするため、データを慎重に扱います。

• ループバックのみ。 コネクターは 127.0.0.1 にバインドし、ループバック以外のアドレスを拒否します。1.x では 0.0.0.0 にバインドされており、ネットワーク上の誰でもアクセスできました。
• 拡張機能がループバックの外に出ることはありません。 1.x はプライベートネットワークの範囲をスキャンし、既知の文字列で応答したホストを採用していました。そのため、共有 Wi-Fi の利用者なら誰でもログやスクリーンショットを受信できる可能性がありました。このスキャンは廃止されました。
• 認証が必要です。 HTTP API には実行ごとのベアラートークンが必要です。URL 内のトークンは拒否されます。拡張機能の WebSocket にも同じトークンが必要です。拡張機能は、ブラウザー拡張機能のオリジンからの要求にのみ応答するループバックのペアリングルートからトークンを取得し、/.identity からトークンが漏れることはありません。--extension-id を指定すると、指定した拡張機能のみを受け入れます。
• 認証情報は受信時にサニタイズされます。 Authorization、Cookie などのヘッダーに加え、キャプチャした文字列内のあらゆる場所で見つかった JWT、クラウドキー、ベンダートークンは [REDACTED] に置き換えられます。
• ヘッダーは方向ごとに既定で無効になっており、明示的に要求されない限りストレージの値は伏せられます。
• Cookie へのアクセスは任意の権限です。 拡張機能が既定で保持しているものではなく、パネルから許可します。
• デバッガーのバナーは表示されたままです。 Chrome の「このブラウザーでデバッグを開始しました」という警告は安全対策です。意図的な仕様であり、このプロジェクトが非表示にすることはありません。デバッガーを接続しないキャプチャ経路ではバナーが表示されませんが、これはバナーを消す方法ではありません。
• 監査によって内部ネットワークにアクセスすることはありません。 監査では URL を受け取ります。呼び出し元が、信頼できないページを読み込むモデルである可能性もあります。リンクローカルアドレスやクラウドのメタデータアドレスは監査しません。localhost またはプライベートネットワーク上のページを監査するのは、接続済みタブで開いている間（または --audit-allow-origin で許可リストに登録されている場合）のみです。また、監査用ブラウザーが行うすべてのリクエストは、リダイレクトやサブリソースも含め、発生時に再度チェックされます。ローカルページが読み込めるのは、タブで開いているか許可リストに登録されているローカルオリジンのみです。そのため、アプリが別のローカルポートの API を呼び出す場合は、そのポートも開くか、許可リストに登録してください。監査はシステムプロキシを経由せず、直接接続します。ホスト名の実際の接続先を隠す偽 IP プロキシ（Clash、sing-box、Surge）を使用している場合、--audit-allow-private-network を指定しない限り監査は拒否されます。詳しくは SECURITY.md を参照してください。

脆弱性は SECURITY.md から報告してください。

設定

フラグ、または対応する BROWSER_TOOLS_* 環境変数を指定します。

フラグ	目的
--port <n>	コネクタのポート（デフォルトは 3025）
--screenshot-dir <path>	スクリーンショットの保存先
--only <a,b>	MCP とローカル API の両方で、指定したツールのみを公開します
--exclude <a,b>	MCP とローカル API の両方で、指定したツールを非表示にします
--allow-actions	ローカル API による再読み込み、キャプチャ、消去、設定変更、タブ選択を許可します。指定しない場合は、BrowserTools パネルで確認してください。コネクタを埋め込むプロセス内の MCP ツールには、この制限は適用されません
--extension-id <id>	この拡張機能のみがペアリングして接続できます
--doctor	セットアップを確認して終了します
--verbose	キャプチャした各エントリを到着時に表示します
--host <addr>	バインドするループバックアドレス（デフォルトは 127.0.0.1）
--connect <url>	別の場所ですでに実行中のコネクタに接続します
--token <t>	--connect で使用する認証トークン
--no-redact	認証情報の削除を無効にします（推奨されません）
--audit-allow-origin <o,o>	タブを開かずに監査対象にできる、または読み込めるループバック／プライベートオリジン
--audit-allow-private-network	監査自身のポートを除くすべてのループバック／プライベートアドレスへの監査アクセスを許可します（推奨されません）。偽 IP プロキシの背後で使用する場合にも必要です

複数の MCP クライアントでブラウザーセッションを共有するには、コネクタを npx @agentdeskai/browser-tools-server で一度起動します。各クライアントは 自動的に接続します。ローカル API には、そのプロセスの --only、--exclude、 --allow-actions、--extension-id が適用されます。接続するクライアントの --only／--exclude は、そのクライアントから見えるツールを引き続き制限します。

既知の制限事項

• ネットワークキャプチャは DevTools を開いた時点で開始されます。それ以前に 完了したリクエストは記録されません。ページの読み込み全体をキャプチャするには、 ページを再読み込みしてください。
• スクリーンショットにはバイト数の上限（デフォルトで 3 MB の screenshotMaxBytes）があります。上限を超えるキャプチャは JPEG に再エンコードされ、 それでも大きすぎる場合は縮小されます。高 DPI ディスプレイで高密度なコンテンツを ビューポートキャプチャすると、13 MB を超えることがあります。これはモデルの コンテキストに収まらず、新しい MCP 標準入出力トランスポートで適用される 読み取りバッファの上限も超えます。画像が収まらない場合はディスクに保存され、 ツールはインライン画像の代わりにパスを返します。
• コンソールキャプチャはデフォルトで DevTools プロトコルを使用するため、Chrome に 「このブラウザはデバッグ中です」というバナーが表示されます。このバナーは意図的なもので、 非表示にはなりません。デバッガーを接続せずにコンソールをキャプチャするには、 パネルのキャプチャモードを Wrap page console に切り替えてください。
• Firefox は検証されていません。 拡張機能はクロスブラウザー対応として記述されており、 browser／chrome シム、browser_specific_settings、および chrome.debugger を必要としないキャプチャモードを備えていますが、Firefox で 読み込まれたことはなく、テストスイートでも検証されていません。特にスクリーンショットは DevTools プロトコルを使用するため、Firefox では動作しません。実際に実行した人が 確認するまでは、Firefox は非対応として扱ってください。どちらの場合も報告を歓迎します。
• 監査では別のブラウザーを起動するため、最大 1 分かかります。Chromium ベースの ブラウザーであれば、Chrome、Chromium、Brave、Edge、Vivaldi、Opera、Arc のいずれも 使用できます。使用されるブラウザーは --doctor で確認できます。上書きするには CHROME_PATH を設定してください。Arc は可能な範囲でサポートしていますが、 ヘッドレスモードでは検証されていません。

開発

npm install
npm run build
npm test           # unit + integration, no browser required
npm run test:e2e   # real Chromium with the extension loaded (headless)

npm test は数秒で実行できます。エンドツーエンドテストスイートは、拡張機能を インストールした Chromium を起動し、フィクスチャページを操作して、キャプチャの 全経路を検証します。ヘッドレスで実行されます。ウィンドウを表示するには HEADED=1 を設定してください。事前に npx playwright install chromium を実行してください。

ライセンス

MIT