troubleshooting

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

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

ステップ 1：設定を見つけて読み込む

最初に、MCP 設定ファイルを探して読み込んでください。ユーザーのワークスペース内で、次のファイルを検索します：.mcp.json、gemini-extension.json、.claude/settings.json、.vscode/launch.json、または .gemini/settings.json。

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

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

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

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

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

エラー：Could not find DevToolsActivePort

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

まず、Chrome が起動しており、適切に設定されていることを確認できるようユーザーを案内してください。すぐに --browserUrl への切り替えを提案してはいけません。次の手順を正確に実行してください。

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

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

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

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

症状：ツールが不足している／利用できるツールが 9 個のみ

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

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

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

拡張機能に関連するツール（install_extension など）が利用できない場合や、読み込んだ拡張機能が動作しない場合：

1. --categoryExtensions フラグを確認する：拡張機能カテゴリのツールを有効にするため、このフラグが MCP サーバーの設定に渡されていることを確認します。
2. MCP サーバーが既存のインスタンスに接続するのではなく、Chrome を起動するよう設定されていることを確認する：Chrome 149 より前のバージョンでは、既存のインスタンスに接続すると拡張機能を読み込めません（--auto-connect、--browserUrl）。

その他のよくあるエラー

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

• Target closed
• "Tool not found"（ナビゲーションとスクリーンショットのツールのみを有効にする --slim を使用しているか確認します）。
• 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 環境を確認します。
• さらに情報が必要な場合は、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 を確認するよう案内できます。