chrome-debug-mcp

chrome-debug-mcp は、非同期 Rust ベースの Model Context Protocol (MCP) サーバーであり、AI エージェントや大規模言語モデルが Chrome DevTools Protocol (CDP) を介して Chromium ベースのブラウザをネイティブに制御、自動化、デバッグできるようにします。

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

• pause_on_load: デバッガを有効にし、ページのリロードをトリガーして、最初に解析されたスクリプト文で実行を一時停止します。

• search_scripts: すべての解析済みスクリプトコンテキストを横断してクエリを検索し、ブレークポイントの行と列を正確に特定します。

• set_breakpoint: script_id、url、または正確な script_hash を使用して、精密な JS ブレークポイントを設定します。

• evaluate_on_call_frame: 現在一時停止中のデバッガのコールフレームの ローカルスコープ 内で、JavaScript 式を直接評価します。

• step_over: 次の式の行をステップオーバーします。

• resume: 一時停止を解除して実行を再開します。

• remove_breakpoint: 以前に設定したブレークポイントを削除します。

🧩 WebMCP（ページ公開ツール） WEB_MCP 機能プリセットを指定して Chrome を再起動する必要があります（restart_chrome を参照）。

• webmcp_list_tools: 現在のページがブラウザに公開しているツールを一覧表示します（名前、説明、inputSchema、frameId）。

• 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 インスタンスを起動したりファイルシステムを変更したりせずに、単独で実行できるように設計されています。

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

⚙️ 設定

デフォルトでは、MCP サーバーは cdp-browser-lite のクロスプラットフォーム検索を通じて 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）を検索します。これは、サーバーが以前ハードコードしていたパスの厳密なスーパーセットです。

引数:

• --local: ナビゲーションをローカルアドレスのみに制限します（localhost、127.0.0.1、192.168.x.x、または *.local）。セキュリティ上、強く推奨されます。

• --headless: Chrome をヘッドレスモード（GUI なし）で実行します。Docker やサーバー環境に必須です。

• --user-profile: 新しいプロファイルの代わりに、デフォルトのシステムユーザープロファイル（セッション、Cookie など）を使用します。リサーチセッション中の繰り返しのログインを避けるのに役立ちます。

• --host: Chrome インスタンスのターゲットホストを指定します（デフォルト: 127.0.0.1）。コンテナからホストマシンに接続するには host.docker.internal を使用します。

• --port: リモートデバッグポートを指定します（デフォルト: 9222）。

• --enable-automation: 「自動化ソフトウェアによって制御されています」というインフォバーを有効にします。

• --max-instances: 同時に実行できる Chrome インスタンスの最大数を制限します（デフォルト: 8）。--user-profile が設定されている場合は無視されます。

環境変数:

• CHROME_PATH: Chrome 実行ファイルへのパスを明示的に定義します。

Related MCP server: chrome-devtools-mcp

🐳 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 サーバーをネイティブにインストールして実行する最も簡単な方法は、Rust の Cargo を使用するか、プリコンパイル済みバイナリをダウンロードすることです。Chrome を手動で起動する必要はもうありません。MCP サーバーが正しいデバッグフラグを付けて、表示可能な Chrome インスタンスを自動的に起動します。

1. インストール

オプション A: プリコンパイル済みバイナリ（推奨） Releases ページにアクセスし、お使いのプラットフォーム（macOS、Windows、Linux）用のネイティブ実行ファイルをダウンロードします。Windows 用の .msi インストーラと、UNIX システム用のシェルスクリプトを提供しています。

オプション B: Cargo でインストール

cargo install --git https://github.com/raultov/chrome-debug-mcp

オプション C: シェルスクリプトでインストール（Unix）

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

2. 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 でサーバーを追加して有効化するには:

claude mcp add chrome-debug-mcp chrome-debug-mcp

3. 使用方法

接続すると、最初のコマンドが実行されたときに AI エージェントが自動的に Chrome の起動を処理します。ブラウザは表示されたままになるため、デバッグプロセスを視覚的に追跡できます。

4. エージェントワークフローとマルチインスタンスガイド

LLM は、いくつかの最適化されたパターンを使用してこのサーバーを操作できます:

A. 分離されたマルチインスタンスシナリオ

自動化されたブラウザセッションを実行する場合、Cookie の汚染やタブの衝突を防ぐために、別々の Chrome プロセスを起動できます:

1. label: "user-session-1" またはオプションのプロキシサーバー設定を指定して open_instance を呼び出します。これにより、一意の instance_id（例: chrome-2）が返されます。

2. instance_id を navigate、evaluate_js、webmcp_list_tools などの下流のツールに明示的に渡します。

3. 完了したら close_instance を使用してリソースをクリーンアップします。

B. WebMCP の使用

WebMCP をサポートするページ（例: https://www.knot.kz/#/agent-tools）に移動した場合:

1. Web ページによって登録されたツールは、webmcp_list_tools を使用して取得できます。

2. デフォルトでは、安全性のため WEB_MCP は無効になっています。ツールリストが空の場合は、features: ["WEB_MCP"] を指定して restart_chrome を呼び出し、その後 reload を実行します。

3. webmcp_invoke_tool を使用して、入力 JSON 引数を指定してページツールを呼び出します。同意ダイアログが Web ページ上の実行を一時停止した場合、ツールは 30 秒後にタイムアウトしますが、呼び出しは保留中のままになります。webmcp_get_invocation を使用して結果をポーリングできます。

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

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

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

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

📖 なぜこの MCP サーバーなのか？

Puppeteer/Playwright ラッパーのような他の統合サーバーは高レベルで重く、通常、実際の対話型ステップバイステップデバッガを公開することに失敗します。この MCP サーバーは生の CDP メッセージを使用し、それらを LLM ツールに 1:1 でマッピングします。これにより、インテリジェントエージェントは JS を文字どおりステップオーバーし、ローカルスコープの変数をネイティブに読み取り、V8 コンパイラコンテキスト内を検索し、スクリプトがクラッシュする理由を正確に理解できます。

📜 ライセンス

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