Chrome Debug Mcp

chrome-debug-mcp

chrome-debug-mcp は、AI エージェントや LLM が Chrome DevTools Protocol（CDP） を介して Chromium ベースのブラウザーをネイティブに制御、自動化、デバッグできる、非同期の Rust ベース Model Context Protocol（MCP） サーバーです。単一の依存関係のないバイナリとして Rust で記述されていますが、ほかの MCP サーバーと同様に、npx -y @raultov/chrome-debug-mcp、Homebrew、または1行のインストーラーでインストールできます。Rust ツールチェーンは不要です。

内部では cdp-browser-lite を使用しています（このライブラリは cdp-lite クライアントを再エクスポートします）。この MCP サーバーは重い抽象化を介さず、ブラウザーに直接接続することで、エディターやチャットインターフェースからライブデバッグセッションを実行できます。v0.2.0 以降は、Chrome プロセスのライフサイクルも自動的に管理できます。

---

✨ 機能

このサーバーは、CDP ドメインとネイティブなプロセス管理によって分類された一連のツールをネイティブに実装しています。 🛡️ プライバシーとセキュリティ

• デーモンの安定性とライフサイクル（v1.5.0）：

  • ナビゲーションごとの保持数制限：NetworkState は、ナビゲーションごとのネットワークリクエスト数を自動的に最大1,000件に制限し、Page.frameNavigated によって切り替わるトップレベルのナビゲーションを最大3件保持します。WebSocket フレームは接続ごとに最大500件、コンソールログは最大1,000件に制限されます。
  • ワーカーの正常な終了：イベントポンプタスクは RAII ハンドル（ListenerHandles）で管理され、タブが閉じられた場合やブラウザー接続がリセットされた場合に自動的に中止されます。
  • バージョンの照合と警告：list_instances は Browser.getVersion で検出した browser_version の情報を報告し、Chrome のメジャーバージョンが 120 未満の場合は警告を追加します。
  • 具体的な検証エラー：タブとインスタンスの ID 検索エラーでは、すべてのアクティブな ID を一覧表示し、ブラウザーの再起動によって以前のタブハンドルが無効になった場合のヒントを提示します。

• 分離されたプロファイル（デフォルト）：MCP サーバーが Chrome を起動するたびに、システムの一時ディレクトリに新しい一時ユーザープロファイルを作成します。このプロファイルはメインのブラウザープロファイルから完全に分離されており、ブラウザーの停止時に削除されるため、あるセッションの Cookie、履歴、保存済みパスワード、セッションデータが次のセッションに引き継がれることはありません。

• シークレットモードのような動作：デフォルトでは、個人アカウントの Cookie、履歴、保存済みパスワード、セッションデータは管理対象のインスタンスと共有されません。

• 本人性の保護：LLM がブラウザーを完全に制御できる場合でも、明示的に許可されない限り、ログイン済みのセッション（Google、GitHub、銀行など）にアクセスしたり、ユーザーになりすましたりすることはできません。

• Cookie のインポート（--allow-cookie-import）：--allow-cookie-import フラグを指定して起動すると、サーバーはツール（navigate、open_instance、restart_chrome）で copy_cookies: true を受け付け、実際の Chrome セッション Cookie を分離された一時プロファイルに取り込めるようになります。

  • オプトインとユーザーの同意：デフォルトでは無効です。copy_cookies: true を設定する前に、LLM はユーザーに明示的に確認を求める必要があります。
  • クロスプラットフォーム対応：
    • Linux：対応（デスクトップキーリングを使用して AES-128-CBC v11 を復号）。復号に失敗しても気付かない事態を防ぐため、os_crypt.selected_backend をインポートします。
    • macOS：対応（Chrome バイナリの ACL を使用して Keychain v10 を復号）。
    • Windows：対応（os_crypt の DPAPI／App-Bound Encryption を使用して v10／v20 を処理）。
  • 破壊的な再起動のガード：実行中のインスタンスに対して navigate を copy_cookies: true で呼び出すと、開いているすべてのタブの詳細を示すエラーが返されます。Cookie を取り込んだ状態でインスタンスを再起動するには、confirm_restart: true が必要です。
  • セキュリティ：パスワードデータベース（Login Data）は決してコピーされません。

• ユーザープロファイルモード：--user-profile フラグを使用すると、既存のシステムプロファイルで Chrome を起動できます。サイトごとに再認証することなく、LLM がアクティブなセッション（Cookie、保存済みログイン情報など）を利用できるようにしたい場合に便利です。個人のブラウザーデータへのアクセスを LLM に許可することになるため、注意して使用してください。

  • ⚠️ --user-profile に関する注意：Chrome のシングルトンアーキテクチャにより、ブラウザーがすでに開いている場合、起動要求は既存のプロセスに委譲され、デバッグポートを開けません。MCP を起動する前に既存の Chrome インスタンスをすべて終了するか、--remote-debugging-port=9222 フラグを指定してブラウザーを手動で起動してください。 🚀 Chrome インスタンスとタブの管理

• マルチインスタンス対応：動的ポートを使用して、独立した Chrome プロセスを複数同時に起動・制御します。各プロセスには、それぞれ分離されたプロファイルディレクトリが割り当てられます。--max-instances フラグを使って、インスタンス数を制限できます。

• インスタンスレジストリツール：open_instance、list_instances、close_instance を使って、追加のインスタンスを作成、監査、クリーンアップできます。既存のすべてのツールでは、オプションの instance_id を指定して、対象のブラウザーにコマンドを送信できます。

• マルチタブ対応（新機能）：単一の Chrome インスタンス内で複数のタブを同時に制御し、単一の WebSocket 接続を介してイベントストリームとコマンドを多重化します。

  • 自動検出：対象のページが開いたポップアップ（例：window.open()）を自動的に検出して接続し、セッションのタブレジストリに登録します。
  • キャッシュの分離：状態キャッシュ（コンソールメッセージ、ネットワークトラフィック、デバッガーで解析されたスクリプト、WebMCP ツールと呼び出し、カスタム CDP イベント、トレース完了チャンネル）はタブごとに厳密に分離されるため、対象間でイベントが混在することはありません。

• タブレジストリツール（新機能）：

  • open_tab — 新しいタブを開きます。必要に応じて、カスタムラベルと対象 URL を指定できます。他のツールで再利用するための tab_id を含む JSON を返します。
  • list_tabs — インスタンスで開いている登録済みのすべてのタブを、JSON（tab_id、label、target_id、url）と現在アクティブなタブとして一覧表示します。タブが登録されていない場合、ツールはインスタンスのデフォルトの単一タブ接続にフォールバックします。
  • close_tab — ID で指定したタブを閉じ、そのキャッシュ状態をクリーンアップします。新しいアクティブタブを返します。
  • switch_tab — ツール呼び出しで tab_id を省略したときに使われるデフォルトのアクティブタブを切り替え、必要に応じてそのタブを前面に表示します。

• LLM に適したインターフェイス：ライフサイクルツール（open_instance、close_instance、open_tab、list_tabs、switch_tab、close_tab）は構造化された JSON を返すため、エージェントは正規表現で文章を解析せずに呼び出しを連鎖できます。また、説明は標準の MCP テンプレート（副作用、前提条件、戻り値、代替手段）に従っているため、モデルが適切に優先順位を付けられます。

• 対象ルーティング（新機能）：タブを対象とするすべてのツールでは、オプションの tab_id パラメーターを指定して、コマンドの対象タブを選択し、特定のタブのキャッシュ状態を取得できます。省略した場合は、デフォルトのアクティブタブが対象になります。

• 分離されたプロファイル：デフォルトでは、新しい一時プロファイルを使って Chrome を起動するため、メインブラウザーの Cookie、パスワード、セッションデータは共有されません。

• ユーザープロファイル対応：必要に応じて --user-profile を使い、既存のブラウザーセッションと Cookie を利用できます。

• 動的ポート管理：デフォルトポート（9222）が使用中かどうかを自動的に検出します。

  • CDP を公開している Chrome インスタンス（ユーザーが起動したもの、または別の chrome-debug-mcp インスタンスで管理されているもの）がポートを使用している場合、新しいインスタンスを起動せず、自動的に接続します。
  • 管理対象のプロファイルは一時的なため、ポートごとの状態は永続化されません。同じポートを共有する 2 つ目のサーバーは、同じブラウザーを共有するだけであり、接続済みのインスタンスを終了することはありません。

• Docker とヘッドレスに対応：Docker 環境に完全対応しています。--headless フラグを使うと、コンテナー内で GUI なしで Chrome を実行できます。

• リモート／ホスト接続：別のマシンまたはホストマシンで実行中の Chrome インスタンスに接続するには、--host 引数を使用します（例：コンテナー内から --host host.docker.internal を指定します）。

• 自動化インフォバーの表示（任意）：--enable-automation フラグを追加すると、ネイティブの「Chrome is being controlled by automated test software」というメッセージを明示的に表示できます。より目立たない操作を実現するため、デフォルトでは無効になっています。

• プロキシサポート：restart_chrome で省略可能な proxy_server 引数を受け付けるようになり、プロキシ経由で通信するように Chrome を起動できます。

• 自動起動：指定されたポートで Chrome が実行中かどうかを自動検出します。実行されていない場合は、必要なフラグを付けて新しいインスタンスを起動します。

• restart_chrome：管理対象の Chrome インスタンスを再起動します。

• 機能プリセット：restart_chrome では省略可能な features 配列を受け付けるため、クライアントは再起動ごとに追加のブラウザー機能を有効にできます。これは固定された選択肢であり、ツールがコマンドラインインジェクションの経路にならないよう、任意の Chrome フラグは意図的に受け付けません。

  • WEBGL_SOFTWARE — SwiftShader ソフトウェア WebGL（--use-gl=angle、--use-angle=swiftshader、--enable-unsafe-swiftshader）を強制します。コンテナーなど、GPU のない環境向けです。

  プリセットは、その呼び出しで起動したインスタンスに適用されます。後続の restart_chrome で features を省略すると、proxy_server と同様にプリセットが解除されます。

• stop_chrome：管理対象の Chrome インスタンスを正常に終了します（SIGTERM／SIGINT を送信し、失敗した場合は SIGKILL にフォールバックします）。

• 堅牢なライフサイクル管理：Chrome プロセスが残存する問題を修正しました。一時プロファイルは停止時に削除され、cdp-browser-lite は強制終了後に残った孤立プロファイルディレクトリを削除します。また、起動フラグとプロファイルのパッチ適用により、「Chrome didn't shut down correctly」の復元ダイアログを抑制します。

• ⚠️ 動作の変更：管理対象の Chrome インスタンスは、MCP サーバープロセスの終了時（クラッシュを含む）に終了するようになりました。以前はサーバーがクラッシュしても管理対象の Chrome は終了せず、再起動時に再接続されていましたが、今後は終了します。接続済みの（ユーザーが起動した）Chrome インスタンスが終了されることはありません。

🔐 プロキシ認証

• enable_proxy_auth：Fetch CDP ドメインをフックして、ユーザーから提供された認証情報を使用し、プロキシ認証のチャレンジを自動的に処理します。サーバーを --proxy-server 付きで起動した場合にのみ公開されます。
• 堅牢性の向上：応答の遅い住宅用プロキシに対応するため、30 秒のタイムアウトを設定しています。また、バックグラウンドリクエストの破損を防ぐため、デフォルトでは Document リクエストのみをインターセプトします。
• 事前ウォームアップと認証情報：http://api.ipify.org?format=json を使用してプロキシ接続を事前にウォームアップします。--proxy-username／--proxy-password 経由で渡された認証情報、またはツールの引数で渡された認証情報を使用できます。

🖱️ ユーザー入力

• click_element：CSS セレクターを使用し、指定した要素をネイティブのマウスクリックで操作します。要素の中央座標を計算し、CDP のマウスイベントを直接送信します。
• fill_input：指定したテキストを DOM 内の入力フィールドに入力します。CSS セレクターで要素にフォーカスを当ててから、ネイティブの CDP Input.insertText を使用します。
• scroll：ページをピクセル単位またはビューポートの高さ（ページ単位）でスクロールするか、特定の要素までスクロールします。遅延読み込みコンテンツや無限スクロールとの操作に不可欠です。

📡 ネットワークの検査

• get_network_logs：インターセプトされたネットワークリクエスト（REST／HTTP）と WebSocket フレームを取得します。
• 高度なフィルタリング：URL、リソースタイプ、WebSocket の方向、またはペイロードの内容でログをフィルタリングできます。
• ペイロードの検査：リクエスト／レスポンスの全ヘッダー、REST レスポンスボディ、WebSocket フレームにアクセスできます。
• コンテキストに配慮した最適化：LLM のコンテキストウィンドウがログであふれないようにする、任意の「summary mode」を利用できます。

🪵 コンソールとエラー

• get_console_logs：ブラウザーのコンソールログを取得します。console.log／warn／error の呼び出し、例外、ネットワークエラーが含まれます。ページスクリプトやエラーのトラブルシューティングに不可欠です。ログレベルによるフィルタリングと、状態を効率的に管理するための clear フラグも利用できます。 ⚡ パフォーマンスとプロファイリング
• get_performance_metrics：ブラウザーから実行時のパフォーマンス指標（JS ヒープサイズ、DOM ノード数、レイアウト時間など）を取得します。ページのメモリ使用量と計算負荷を手早く確認するのに便利です。
• profile_page_performance：ページのパフォーマンストレースを記録して分析します。Core Web Vitals（FCP、LCP、DCL、Load）を自動的に計算し、上位の Long Tasks（メインスレッドをブロックする処理）を特定します。必要に応じて、キャッシュを無効にしてページを再読み込みし、コールドスタートをシミュレートできます。

🌐 ページとランタイムの制御

• capture_screenshot：現在のページ（またはページ全体のレイアウト）のスクリーンショットを撮影し、base64 エンコードされた画像ブロックとして LLM クライアントに返します。
• navigate：アクティブなタブを指定した URL に移動します。
• reload：現在のページを再読み込みします。
• inspect_dom：HTML 全体、または検索クエリの周辺にあるスマートスニペットを取得します。
  • コンテキスト検索：特定のテキストを検索し、その周辺の指定可能な文字数を取得します。
  • トークン効率：大きなページでのコンテキストウィンドウの使用量を大幅に削減します。
• evaluate_js：ページのコンテキスト内で、任意の JavaScript 式をグローバルに実行します。

🐞 ライブデバッグと実行制御

• pause_on_load：デバッガーを有効にしてページを再読み込みし、最初に解析されたスクリプト文で実行を一時停止します。
• search_scripts：解析済みのすべてのスクリプトコンテキストをクエリで検索し、ブレークポイントを設定する行と列を正確に見つけます。
• set_breakpoint：script_id、url、または完全一致する script_hash を使って、正確な JS ブレークポイントを設定します。
• evaluate_on_call_frame：現在デバッガーが一時停止している呼び出しフレームのローカルスコープ内で、JavaScript 式を直接評価します。
• step_over：次の式の行をステップオーバーします。
• resume：一時停止を解除し、実行を再開します。
• remove_breakpoint：以前に設定したブレークポイントを削除します。

🧩 WebMCP（ページ公開ツール） --enable-webmcp を指定してサーバーを起動し、ツール（webmcp_*）を公開して Chromium の機能スイッチ（--enable-features=WebMCPTesting,DevToolsWebMCPSupport）を有効にする必要があります。すべての WebMCP ツールは、特定のタブを対象にするための省略可能な tab_id を受け付けます（省略するとアクティブなタブが使われます）。

• webmcp_list_tools：現在のページがブラウザーに公開しているツール（名前、説明、inputSchema、frameId）を一覧表示します。ドキュメントをまたぐナビゲーションのたびにタブのツールキャッシュは消去され、WebMCP.enable を通じて再同期されるため、出力は document.modelContext.getTools() と一致し続けます。同一ドキュメント内のナビゲーション（ハッシュ／履歴）ではキャッシュが保持されます。リスナーは CDP ドメインが有効になる前に登録されるため、Chrome による権威ある再送（WebMCP.enable が toolsAdded リスト全体を再送信）が捕捉されます。新しいツールは WebMCP.toolsAdded から数ミリ秒以内にここへ反映されます（Chrome 153 での測定値は 1～491 ms。1.5.5 より前は 2～17 秒でした）。イベントチャネルでイベントの欠落が報告された場合、ツールキャッシュは信頼せず、ソースから再構築されます。

• webmcp_invoke_tool：名前でページツールを呼び出します。input はツールの inputSchema に一致するJSON オブジェクト文字列です（例："{}" または "{\"product\":\"knot\"}"）。結果を最大 30 秒間待ちます。

• webmcp_get_invocation：invocationId で呼び出しのステータス（Pending／Completed／Error／Canceled）と結果を返します。ブロッキングなしで実行されます。

• webmcp_list_invocations：セッション内のすべての呼び出しをステータスとともに一覧表示します。status による絞り込みも指定できます。

  ⚠️ 同意ダイアログ：副作用を伴うページツール（クリップボードへの書き込み、フォーム送信など）では、ページ上に人間がクリックする必要のある確認ダイアログが表示されることがあります。その場合、webmcp_invoke_tool は invocationId を含むタイムアウトエラーを返します。呼び出しは Pending のまま維持され（キャンセルはされません）、ユーザーが承認または拒否した後に webmcp_get_invocation で状態を確認できます。 🧪 安定性と信頼性

• 広範なユニットテスト：イベント処理とツールのデシリアライズの信頼性を確保する包括的なテストスイートです。特に debugger ドメインを重点的にテストします。

• 副作用のないテスト：すべてのユニットテストは、実際の Chrome インスタンスを起動したり、ファイルシステムを変更したりせず、分離して実行できるように設計されています。

• 内部のリファクタリング：トレイトと依存性注入によってコアロジックを分離し、長期的な保守性を確保しています。

---

📦 インストール

どの方法でも、各 GitHub Release で公開されている同じプリコンパイル済みバイナリがインストールされます。Rust ツールチェーンが必要なのは、Cargo を使う方法とソースからインストールする方法のみです。npm パッケージは軽量なラッパーで、postinstall が GitHub Releases からお使いのプラットフォーム用のプリコンパイル済みバイナリを取得します。コンパイルも Rust ツールチェーンも必要ありません。

⚠️ npm では必ずスコープ付きの名前 @raultov/chrome-debug-mcp を使用してください。 npm にあるスコープなしの chrome-debug-mcp は、別の無関係なプロジェクトです。

手間をかけずにインストールしたいですか？以下のワンプロンプト方式を使えば、AI エージェントがすべて行います。それ以外の方法はプラットフォームごとにまとめ、人気順に並べています。

🤖 ワンプロンプトインストール（すべてのプラットフォーム）

このプロンプトを任意の AI コーディングエージェントのチャット（Claude Code、opencode、Cursor、Codex CLI、Copilot など）に貼り付けると、サーバーをインストールし、お使いのマシンで検出した MCP 対応クライアントすべてに登録します。

Install and set up the chrome-debug-mcp MCP server on this machine. Do not launch Chrome yourself — the server launches and manages it automatically.

1. Install the server binary with the first method that works on this OS:
   - Homebrew available (macOS/Linux): brew install raultov/tap/chrome-debug-mcp
   - Node.js >= 14 available (any OS): npm install -g @raultov/chrome-debug-mcp
   - macOS/Linux fallback: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh
   - Windows fallback: download and run the .msi from https://github.com/raultov/chrome-debug-mcp/releases/latest
   Verify with: chrome-debug-mcp --version (add the install dir to PATH if it is not found).

2. Register the MCP server with every AI client you detect on this machine:
   - Claude Code: claude mcp add --scope user chrome-debug-mcp chrome-debug-mcp
   - opencode (and agy, its bridge): merge into ~/.config/opencode/opencode.json —
     "mcp": { "chrome-debug-mcp": { "type": "local", "command": ["chrome-debug-mcp"] } }
   - Codex CLI: append to ~/.codex/config.toml —
     [mcp_servers.chrome-debug-mcp]
     command = "chrome-debug-mcp"
   - Any other MCP-capable client (Cursor, Windsurf, VS Code, ...): add it with its own MCP settings, command "chrome-debug-mcp" with no arguments.

3. Report what you installed and which clients you configured, and remind me to restart each client so the MCP server loads. Do not enable --user-profile or cookie import unless I ask for them.

macOS

1. Homebrew — macOS では一般的な方法です：

brew install raultov/tap/chrome-debug-mcp

この formula は GitHub Releases からプリコンパイル済みバイナリ（Apple Silicon と Intel）を直接取得します。brew upgrade を実行すると、リリースのたびに最新の状態に保てます。

2. npm / npx — MCP クライアントで一般的な方法です（Node.js >= 14 が必要です）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

3. シェルインストーラー — ~/.cargo/bin にインストールするワンライナーです：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh

4. Cargo — すでに Rust をお使いの場合：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手動ダウンロード — Releases ページから aarch64-apple-darwin または x86_64-apple-darwin の .tar.xz アーカイブをダウンロードします。

Linux

1. npm / npx — MCP クライアントで一般的な方法です（Node.js >= 14 が必要です）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

2. シェルインストーラー — ~/.cargo/bin にインストールするワンライナーです：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh

Linux バイナリには glibc >= 2.35 が必要です（Ubuntu 22.04+、Debian 12+、Fedora 36+）。

3. Homebrew（Linuxbrew） — すでに Homebrew-on-Linux をお使いの場合：

brew install raultov/tap/chrome-debug-mcp

4. Cargo — すでに Rust をお使いの場合：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手動ダウンロード — Releases ページから x86_64-unknown-linux-gnu または aarch64-unknown-linux-gnu の .tar.xz アーカイブをダウンロードします。

Windows

1. npm / npx — MCP クライアントで一般的な方法です（Node.js >= 14 が必要です）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

2. MSI インストーラー — Windows ネイティブのインストール方法です。Releases ページから chrome-debug-mcp-x86_64-pc-windows-msvc.msi をダウンロードして、ダブルクリックします。

3. PowerShell インストーラー — ワンライナーです：

powershell -ExecutionPolicy Bypass -c "irm https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.ps1 | iex"

4. Cargo — すでに Rust をお使いの場合：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手動ダウンロード — Releases ページから x86_64-pc-windows-msvc の .zip アーカイブをダウンロードします。

Docker とクラウド

コンテナーによる分離、ホストとコンテナーのハイブリッドモード、インストール不要の Glama クラウドデプロイについては、以下のDocker とヘッドレス環境での使用セクションをご覧ください。

ソースからインストール

以下の**コンパイル（ソースから）**をご覧ください。

---

⚙️ 設定

MCP サーバーは、クロスプラットフォームの検索によって Chrome 実行ファイルを検出します。最初に CHROME_PATH 環境変数を確認し（最優先）、次に PATH 内の一般的なバイナリ（google-chrome、google-chrome-stable、chromium、chromium-browser）を確認し、最後に OS の標準インストールパスを確認します（macOS では /Applications/Google Chrome.app/...、Windows では chrome.exe の場所、Linux では /usr/bin/google-chrome、/opt/google/chrome/chrome、/snap/bin/chromium）。

---

1. MCP サーバーの起動フラグ（CLI）

これらのフラグは、起動時の MCP サーバープロセスを設定します。chrome-debug-mcp の起動時にコマンドラインで渡すか、クライアントの args / command 定義に指定してください。

フラグ	説明	デフォルト	指定可能な値／形式
--local	ナビゲーションをローカルアドレス（localhost、127.0.0.1、192.168.x.x、*.local）のみに制限します。セキュリティ上、強く推奨します。	off	フラグあり（on）または省略（off）
--enable-automation	ネイティブの「Chrome は自動テストソフトウェアによって制御されています」という情報バーを表示します。	off	フラグあり（on）または省略（off）
--user-profile	新しい隔離された一時プロファイルの代わりに、システムのデフォルトの Chrome プロファイル（Cookie、保存済みログイン情報）を使用します。	off	フラグあり（on）または省略（off）
--allow-cookie-import	ツール（navigate、open_instance、restart_chrome）で Cookie インポート用パラメーター（copy_cookies、source_profile、confirm_restart）を利用できるようにします。	off	フラグあり（on）または省略（off）
--enable-webmcp	Chrome インスタンスで WebMCP テスト用スイッチ（--enable-features=WebMCPTesting,DevToolsWebMCPSupport）を有効にし、WebMCP ツール（webmcp_*）を利用できるようにします。別名：--webmcp。	off	フラグあり（on）または省略（off）
--proxy-server <URL>	Chrome インスタンスのプロキシサーバーを設定し、プロキシツール（enable_proxy_auth）を利用できるようにします。別名：--proxy。	(なし)	有効なプロキシ URL（例：http://proxy.example.com:8080）
--proxy-username <USER>	プロキシ認証のデフォルトのユーザー名です。	(なし)	文字列のユーザー名
--proxy-password <PASS>	プロキシ認証のデフォルトのパスワードです。	(なし)	文字列のパスワード
--headless	Chrome をヘッドレスモード（GUI なし）で実行します。GPU のない環境や Docker 環境では必須です。	off	フラグあり（on）または省略（off）
--host <HOST>	Chrome のリモートデバッグ接続先のホスト IP アドレスです。	127.0.0.1	有効な IP アドレス（例：127.0.0.1、host.docker.internal）
--port <PORT>	プライマリインスタンスの Chrome リモートデバッグポートです。	9222	使用可能な TCP ポート（1～65535）
--max-instances <N>	インスタンスプールで同時に使用できる独立した Chrome インスタンスの最大数です。--user-profile が設定されている場合は無視されます。	8	正の整数（例：1、4、16）

---

2. 環境変数

変数	説明	デフォルト	値の形式
CHROME_PATH	Chrome または Chromium のバイナリへの絶対パスを明示的に指定します。バイナリの自動検出パスをすべて上書きします。	(未設定)	絶対ファイルパス（例：/usr/bin/google-chrome-stable または C:\Program Files\Google\Chrome\Application\chrome.exe）

---

3. Chrome インスタンスの起動スイッチとプリセット

MCP サーバーが Chrome を起動するとき、起動フラグ、動的に割り当てられたポート、各インスタンスで要求された機能プリセット（例：open_instance または restart_chrome 経由）に基づいてスイッチを構成します。

A. 適用される Chromium ネイティブスイッチ

Chrome／Chromium ネイティブスイッチ	chrome-debug-mcp の起動時に...	効果／説明
--remote-debugging-port=<PORT>	--port <PORT> を指定	V8 Inspector CDP WebSocket エンドポイントを指定したポートにバインドします。
--user-data-dir=<TMP_DIR>	--user-profile を省略（デフォルト）	/tmp に独立した一時プロファイルディレクトリを作成し、シャットダウン時に自動的に削除します。
（--user-data-dir スイッチなし）	--user-profile を指定	システムのデフォルトプロファイルの場所（~/.config/google-chrome、Keychain／DPAPI）を使用します。
--headless	--headless を指定	GUI なしでブラウザーを実行します。
--disable-infobars	--enable-automation を省略（デフォルト）	「自動テスト ソフトウェアによって制御されています」という通知バーを非表示にし、より目立たない操作を可能にします。
（--disable-infobars スイッチなし）	--enable-automation を指定	ネイティブの自動化インフォバーを表示します。
--proxy-server="<PROXY_URL>"	--proxy-server <URL> を指定	インスタンスのネットワークトラフィックを指定した HTTP／SOCKS プロキシ経由でルーティングします。
--enable-features=WebMCPTesting,DevToolsWebMCPSupport	--enable-webmcp を指定	Chrome で WebMCP ランタイムテスト API（#enable-webmcp-testing）と DevTools CDP 検査スイッチ（#devtools-webmcp-support）を有効にします。
--user-data-dir=<SEEDED_TMP_DIR>	シードプロファイル／Cookie のインポート（動的）	復号した Chrome Cookie を新しい一時プロファイルのコピーに複製します。

B. 機能プリセット（features パラメーター）

動的ツール（open_instance、restart_chrome）は、機能プリセットを指定する features 配列を受け取ります。

プリセット名	適用される Chrome コマンドラインスイッチ	使用例／目的
"WEBGL_SOFTWARE"	--use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader	GPU のないコンテナーで WebGL のソフトウェアラスタライズに SwiftShader を強制的に使用します。

---

🐳 Docker とヘッドレスでの使用（v1.0.0）

chrome-debug-mcp はコンテナーでの利用に完全対応しています。これにより、LLM で次のような強力なユースケースを実現できます。

1. クラウドデプロイ（Glama 経由）

このサーバーを使用する最も簡単な方法です。Glama は Chrome がプリインストールされた Docker コンテナーを起動します。LLM はローカルでのセットアップなしに、すぐにクラウド上のブラウザーを利用できます。

2. ローカルでの分離利用

ホストマシンに Chrome や Rust をインストールせずに済むよう、すべてを Docker 内で実行します：

docker build -t chrome-mcp .
docker run -i --rm chrome-mcp --headless

3. ハイブリッドモード（コンテナーからホストを制御）

MCP サーバーはセキュアな Docker コンテナー内で実行されますが、実際のデスクトップにある Chrome インスタンスを制御します。これにより、LLM が実際のブラウジングセッションを支援できます：

1. 次のオプションを付けてローカルの Chrome を起動します：--remote-debugging-port=9222
   • 注：このモードでプロキシを使用する場合は、Chrome の起動時に --proxy-server="http://your-proxy:port" フラグも指定する必要があります。
2. コンテナーを実行します：

# On macOS/Windows
docker run -i --rm chrome-mcp --host host.docker.internal

---

🚀 クイックスタート

上記のインストール方法からいずれかを選び、MCP クライアントで chrome-debug-mcp コマンドを指定します。Chrome を手動で起動する必要はもうありません。MCP サーバーが適切なデバッグフラグを付けて、表示可能な Chrome インスタンスを自動的に起動します。

1. MCP クライアントを設定する

このサーバーは Claude Code、agy、codex での動作が十分にテストされ、確認されています。以下のいずれかのモードを使用してサーバーを実行するように AI クライアントを設定してください。

汎用設定（JSON）

ほとんどの MCP クライアント（Claude Code や JSON ベースの設定を使用するクライアントなど）では、この形式を使います。主な使用モードは次の 3 つです。

{
  "mcpServers": {
    "chrome-debug-mcp": {
      "command": "chrome-debug-mcp",
      "args": [],
      "env": {}
    },
    "chrome-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chrome-debug-mcp:v1.0.9", "--headless"]
    },
    "chrome-docker-hybrid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--net=host",
        "chrome-debug-mcp:v1.0.9",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}

注：--net=host を使用する chrome-docker-hybrid モードは、コンテナーから 127.0.0.1 上のローカル Chrome インスタンスにアクセスできるため、Linux では推奨される方法です。

Claude Code

Claude Code でサーバーを追加して有効にします。2 つの位置引数は <name>（Claude 内でのサーバーのラベル）と <command>（起動する実行ファイル）です：

# Run the binary installed by any method above (Homebrew, npm -g, installer, cargo, MSI):
claude mcp add chrome-debug-mcp chrome-debug-mcp
# ...or without installing anything first (Node.js >= 14):
claude mcp add chrome-debug-mcp -- npx -y @raultov/chrome-debug-mcp

2. 使用方法

接続すると、最初のコマンドが実行されたときに、AI エージェントが自動的に Chrome を起動します。デバッグの過程を目視で追えるよう、ブラウザーは表示されたままになります。

3. エージェントのワークフローと複数インスタンスの使い方

LLM は、最適化された以下のパターンを使ってこのサーバーを操作できます。

A. 分離された複数インスタンスのシナリオ

自動ブラウザーセッションを実行する際は、Cookie の汚染やタブの競合を防ぐため、Chrome のプロセスを別々に起動できます。

1. label: "user-session-1" または任意のプロキシサーバー設定を指定して open_instance を呼び出します。固有の instance_id（例：chrome-2）が返されます。
2. navigate、evaluate_js、webmcp_list_tools などの後続ツールに、instance_id を明示的に渡します。
3. 完了したら close_instance を使ってリソースを解放します。

B. WebMCP の使用

WebMCP に対応したページ（例：https://www.knot.kz/#/agent-tools）に移動した場合：

1. Web ページに登録されたツールは、webmcp_list_tools を使って取得できます。
2. 安全のため、WebMCP はデフォルトで無効になっています。WebMCP ツールを公開し、Chrome の WebMCP 機能スイッチ（--enable-features=WebMCPTesting,DevToolsWebMCPSupport）を有効にするには、--enable-webmcp を指定して chrome-debug-mcp を起動します。
3. 入力 JSON 引数を指定して webmcp_invoke_tool を使い、ページのツールを呼び出します。同意ダイアログによって Web ページ上の実行が一時停止した場合、ツールは 30 秒後にタイムアウトしますが、呼び出しは保留されたままになります。webmcp_get_invocation を使って結果をポーリングできます。

---

🛠 コンパイル（ソースから）

ソースからコンパイルする場合：

git clone https://github.com/raultov/chrome-debug-mcp
cd chrome-debug-mcp
cargo build --release

開発とコード品質

make check                                  # Run all local quality gates (fmt, clippy, test, dupes)

# Or run gates individually:
cargo clippy --all-targets -- -D warnings  # Must pass
cargo fmt -- --check                        # Must pass
cargo test --all-targets                    # Run unit tests
cargo dupes check                           # Code duplication check

生成されたバイナリは target/release/chrome-debug-mcp に配置されます。このプロジェクトでは cargo-dist を利用して、GitHub Actions 経由でクロスプラットフォームのネイティブ配布をシームレスに行います。

---

📖 この MCP サーバーを選ぶ理由

Puppeteer／Playwright のラッパーなど、他の統合サーバーは高レベルで動作が重く、実際に操作できるステップごとのデバッガーを公開できないことがよくあります。この MCP サーバーは、生の CDP メッセージを LLM ツールに 1 対 1 で対応付けます。これにより、インテリジェントなエージェントは JS を文字どおりステップオーバーし、ローカルスコープ変数をネイティブに読み取り、V8 コンパイラーのコンテキスト内を検索して、スクリプトがクラッシュする原因を正確に把握できます。

---

📜 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳しくは LICENSE ファイルをご覧ください。