troubleshooting

トラブルシューティングウィザード

ユーザーが Chrome DevTools MCP サーバーを設定し、問題を解決できるよう支援するトラブルシューティングウィザードとして対応します。このスキルが呼び出された場合（例：list_pages、new_page、navigate_page が失敗した場合や、サーバーが起動しない場合）は、以下の手順に沿って診断してください。

ステップ 1：設定を見つけて読み取る

最初に、MCP 設定ファイルを探して読み取ってください。ユーザーのワークスペース内で、次のファイルを検索します：.mcp.json、.vscode/mcp.json、gemini-extension.json、.gemini/settings.json（または、アクセス可能であれば ~/.claude.json など、ユーザー単位のファイル）。

設定ファイルが見つかった場合は、内容を読み取って解釈し、次のような潜在的な問題を特定してください。

• 引数またはフラグが正しくない。
• 環境変数が不足している。
• 互換性のない環境で --autoConnect を使用している。

これらのファイルが見つからない場合に限り、設定ファイルの内容を提示するようユーザーに依頼してください。

ステップ 2：よくある接続エラーを切り分ける

ドキュメントを読んだり、設定変更を提案したりする前に、エラーメッセージが次のよくあるパターンに該当するか確認してください。

エラー：Could not find DevToolsActivePort

このエラーは --autoConnect 機能に特有です。MCP サーバーが、実行中でデバッグ可能な Chrome インスタンスによって作成されたファイルを見つけられないことを意味します。一般的な接続エラーではありません。

主な目的は、Chrome が実行中で、適切に設定されていることを確認できるようユーザーを案内することです。すぐに --browserUrl への切り替えを提案しないでください。必ず次の順序に従ってください。

1. 該当する Chrome のバージョン（エラーに記載されている場合は「Chrome Canary」など）が現在実行中かどうか、ユーザーに確認してください。
2. 実行中だとユーザーが確認した場合は、リモートデバッグを有効にするよう案内してください。 URL と操作を具体的に伝えます：「Chrome で新しいタブを開き、chrome://inspect/#remote-debugging に移動して、『Enable remote debugging』チェックボックスがオンになっていることを確認してください。」
3. ユーザーが両方の手順を確認したら、次に行う操作は list_pages ツールの呼び出しだけにしてください。 接続が成功したかを確認する最も簡単で安全な方法です。元のより複雑なコマンドを、まだ再試行しないでください。
4. list_pages が成功すれば、問題は解決です。 同じエラーで失敗する場合は、その後で --browserUrl の提案やサンドボックス化の問題の確認など、より高度な手順に進むことができます。

症状：サーバーは起動するが、新しい空のプロファイルが作成される

サーバーは正常に起動するものの、list_pages が空のリストを返したり、既存の Chrome インスタンスに接続せず新しいプロファイルを作成したりする場合は、引数に誤記がないか確認してください。

• フラグの誤記を確認する： たとえば、--autoConnect ではなく --autoBronnect になっている場合です。
• 設定を確認する： 引数が想定どおりのフラグと完全に一致していることを確認してください。

症状：ツールが不足している／利用できるツールが少ない

サーバーは正常に起動するものの、list_pages、list_console_messages、get_console_message、list_network_requests など、限られた一部のツールしか利用できない場合は、MCP クライアントが読み取り専用モードを適用している可能性があります。

chrome-devtools-mcp のすべてのツールには、安全で変更を加えないツールを示す readOnlyHint: true、または emulate、click、navigate_page など、ブラウザーの状態を変更するツールを示す readOnlyHint: false が付与されています。すべてのツールを利用するには、ユーザーが MCP クライアントで読み取り専用モードを無効にする必要があります（例：Gemini CLI の「Plan Mode」を終了する、またはクライアントのツール安全性設定を調整する）。

症状：拡張機能のツールが見つからない、または拡張機能の読み込みに失敗する

拡張機能に関連するツール（install_extension など）が利用できない場合や、読み込んだ拡張機能が動作しない場合は、次の手順に従ってください。

1. --categoryExtensions フラグを確認します： 拡張機能カテゴリーのツールを有効にするため、このフラグが MCP サーバーの設定で渡されていることを確認してください。

その他の一般的なエラー

失敗したツール呼び出しまたは MCP の初期化ログから、ほかのエラーメッセージを特定します。

• Target closed
• "Tool not found"（ナビゲーション、スクリプト評価、スクリーンショットのツールのみを有効にする --slim を使用しているか確認してください）。
• pageId が見つからない：ページスコープのツールには pageId 引数が必要です。list_pages を呼び出して、アクティブなページ ID を確認してください。
• ProtocolError: Network.enable timed out または The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• サンドボックスまたはホストの検証に関するエラー。

ステップ 3：既知の問題を確認する

https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md の内容を読み、エラーを既知の問題と照合します。次の点に特に注意してください。

• サンドボックスの制限（macOS Seatbelt、Linux コンテナー）。
• WSL の要件。
• --autoConnect のハンドシェイク、タイムアウト、要件（Chrome 144 以降が起動中である必要があります）。

ステップ 4：設定を作成する

正確なエラーとユーザーの環境（OS、MCP クライアント）に基づいて、適切な MCP 設定スニペットを作成します。次の点を確認してください。

• --autoConnect の代わりに --browser-url=http://127.0.0.1:9222 を渡す必要があるか（例：Claude Desktop のようなサンドボックス環境の場合）。
• Chrome でリモートデバッグを有効にし（chrome://inspect/#remote-debugging）、接続プロンプトを承認する必要があるか。--autoConnect を使用している場合は、これが有効になっていることをユーザーに確認してもらいます。
• 分析用のデバッグログを記録するため、--logFile <absolute_path_to_log_file> を追加する必要があるか。
• Windows で Codex を使用している場合、startup_timeout_ms を増やす必要があるか（例：20000）。

ユーザーの設定が不明な場合は、現在の MCP サーバーの JSON 設定を提示するようユーザーに依頼してください。

ステップ 5：診断コマンドを実行する

問題がまだ明確でない場合は、診断コマンドを実行してサーバーを直接テストします。

• npx chrome-devtools-mcp@latest --help を実行して、インストールと Node.js 環境を確認します。
• さらに情報が必要な場合は、NODE_DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log を実行して詳細なログを記録します。出力を分析し、エラーがないか確認してください。

ステップ 6：GitHub で既存の問題を確認する

https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md に該当するエラーが記載されていない場合は、環境で gh（GitHub CLI）ツールを利用できるか確認します。利用できる場合は、GitHub リポジトリで類似の問題を検索します。

gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all

または、サポートを受けるために https://github.com/ChromeDevTools/chrome-devtools-mcp/issues と https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions を確認するようユーザーに案内できます。