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 (たとえば、エラーに記載されている "Chrome Canary") が現在実行されていることを確認するようにガイドすることです。すぐに --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。
• 設定を確認: 引数が予想されるフラグと正確に一致していることを確認してください。

症状: ツールがない / 9 個のツールしか利用できない

サーバーは正常に起動されますが、ツールの限定されたサブセット (list_pages、get_console_message、lighthouse_audit、take_memory_snapshot など) しか利用できない場合、これは MCP クライアントが 読み取り専用モード を強制しているためと考えられます。

chrome-devtools-mcp のすべてのツールには、readOnlyHint: true (安全な非修正ツール) または readOnlyHint: false (ブラウザの状態を変更するツール (emulate、click、navigate_page など) のいずれかで注釈が付けられています。ツールの完全なスイートにアクセスするには、ユーザーが MCP クライアント内で読み取り専用モードを無効にする必要があります (例: Gemini CLI で「Plan Mode」を終了するか、クライアントのツール安全設定を調整することで)。

症状: 拡張ツールが不足している、または拡張の読み込みに失敗する

拡張機能に関連するツール (install_extension など) が利用できない場合、または読み込んだ拡張機能が機能していない場合:

1. --categoryExtensions フラグをチェック: この拡張機能のカテゴリ ツールを有効にするために、このフラグが MCP サーバー設定で渡されていることを確認してください。
2. MCP サーバーが既存のインスタンスに接続する代わりに Chrome を起動するように設定されていることを確認: 149 より前の Chrome では、既存のインスタンス (--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 <絶対パス> を追加して、分析用のデバッグログをキャプチャします。
• 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 "<エラースニペット>" --state all

代わりに、ユーザーが https://github.com/ChromeDevTools/chrome-devtools-mcp/issues と https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions をチェックしてヘルプを得ることをお勧めできます。