cc_chrome_devtools_mcp_skill

Chrome DevTools Testing Skill

概要

このスキルでは、chrome-devtools-mcp サーバーを介して Chrome DevTools Protocol（CDP）を使用し、Chrome ブラウザーの自動テストとパフォーマンス分析を実行できます。ウェブアプリケーションのテスト、パフォーマンス測定、アクセシビリティ検証、ブラウザー自動化に利用できる、プロフェッショナルグレードのツールを27種類提供します。

主な機能：

• Core Web Vitals（INP、LCP、CLS）によるパフォーマンス分析
• ネットワーク監視と HAR エクスポート
• アクセシビリティツリーの検査
• レスポンシブデザインのテスト
• ブラウザー自動化（フォーム入力、ナビゲーション、操作）
• 複数タブとフレームの管理
• デバイスとネットワーク状況のエミュレーション

ブラウザーのサポート： Chrome/Chromium のみ（stable、beta、dev、canary チャネル）

Node.js の要件： v20.19 以降

クイックスタート

インストール

# Add to Claude Code via CLI
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

# Verify installation
claude mcp list

基本設定

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--isolated=true",
        "--viewport=1920x1080"
      ]
    }
  }
}

重要な注意事項

• ブラウザーは最初のツール使用時に自動起動します（MCP への接続時ではありません）
• セキュリティのため --isolated=true を使用してください（一時的なユーザーデータディレクトリが作成され、自動的にクリーンアップされます）
• デフォルトの動作では、セッション間でユーザーデータディレクトリが共有され、実行ごとにクリアされることはありません
• すべてのブラウザーコンテンツは MCP クライアントに公開されるため、機密データは使用しないでください

現在の Core Web Vitals（2024年3月12日時点）

ページ読み込みの75パーセンタイルで測定される、3つの公式指標です。

1. Interaction to Next Paint（INP） - 2024年3月12日に FID に代わって導入

   • 良好：≤ 200ms
   • 測定対象：入力遅延 + 処理時間 + 表示遅延
   • 要件：実際のユーザー操作（フィールドデータのみ）

2. Largest Contentful Paint（LCP）

   • 良好：≤ 2.5秒
   • 測定対象：メインコンテンツの読み込みパフォーマンス

3. Cumulative Layout Shift（CLS）

   • 良好：≤ 0.1
   • 測定対象：視覚的な安定性

**Total Blocking Time（TBT）**は Core Web Vitals ではありません。INP のラボ環境における代理指標です。

よくあるユースケース

1. パフォーマンステストのワークフロー

Core Web Vitals を測定し、パフォーマンスのボトルネックを分析します。

1. Start performance trace: performance_start_trace
2. Navigate to target URL: navigate_page
3. Wait for page load: wait_for
4. Stop trace and get metrics: performance_stop_trace
5. Analyze specific insights: performance_analyze_insight

取得される指標：

• INP（Interaction to Next Paint）
• LCP（Largest Contentful Paint）の内訳
• CLS（Cumulative Layout Shift）
• TBT（Total Blocking Time - ラボ環境における代理指標）
• ドキュメントのレイテンシ分析

例：

performance_start_trace with reload=true, autoStop=false
wait_for page to stabilize
performance_stop_trace
performance_analyze_insight with insightName="LCPBreakdown"

2. ネットワーク監視と HAR エクスポート

タイミングの詳細とともに、すべての HTTP リクエストとレスポンスを取得します。

1. Navigate to URL: navigate_page
2. List all network requests: list_network_requests
3. Get specific request details: get_network_request

取得されるデータ：

• ヘッダー、本文、Cookie
• タイミング（DNS、接続、SSL、待機、受信）
• リソースタイプ（ドキュメント、スタイルシート、画像、スクリプト、xhr、fetch）
• セキュリティの詳細（プロトコル、暗号スイート）

HAR としてエクスポート： list_network_requests を使用して、HTTP Archive v1.2 形式を生成します。

リクエストをフィルタリング：

list_network_requests with resourceTypes=["xhr", "fetch", "document"]
list_network_requests with pageSize=50, pageIdx=0

3. アクセシビリティ検証

アクセシビリティツリーを検査して、WCAG への準拠を確認します。

1. Navigate to page: navigate_page
2. Take accessibility snapshot: take_snapshot
3. Interact with elements using UIDs

スナップショットで確認できる内容：

• 一意の要素識別子（UID）
• アクセシビリティのロール、名前、プロパティ
• ARIA 属性と算出されたロール
• スクリーンリーダーとの互換性分析
• セマンティック構造の検証

ワークフローの例：

take_snapshot verbose=false (returns text-based a11y tree)
# Identify element UIDs from snapshot
click uid="element-123"
fill uid="input-456" value="test data"

4. レスポンシブデザインのテスト

デバイスやネットワーク状況を変えてテストします。

1. Resize viewport: resize_page width=375 height=667
2. Emulate network: emulate_network throttlingOption="Slow 3G"
3. Emulate CPU: emulate_cpu throttlingRate=4
4. Take screenshot: take_screenshot fullPage=true

デバイスエミュレーションのオプション：

• ビューポートの寸法とデバイスのスケールファクター
• ネットワーク状況：オフライン、Slow 3G、Fast 3G、Slow 4G、Fast 4G
• CPU スロットリング：1～20倍の低速化
• 最大タッチポイント数を指定したタッチエミュレーション

スクリーンショット形式： PNG、JPEG、WebP（画質設定あり）

5. ブラウザー自動化

フォーム入力、ナビゲーション、操作を自動化します。

1. Take snapshot to get element UIDs: take_snapshot
2. Fill form fields: fill_form elements=[{uid, value}, ...]
3. Click buttons: click uid="submit-button"
4. Handle dialogs: handle_dialog action="accept"
5. Wait for results: wait_for text="Success"

操作ツール：

• click（シングルクリック／ダブルクリック）
• fill（入力フィールド、テキストエリア、セレクト）
• fill_form（一度に複数のフィールドを入力）
• hover（マウスオーバー）
• drag（ドラッグ＆ドロップ）
• upload_file（ファイル入力）
• handle_dialog（アラート、確認、プロンプト）

ナビゲーションツール：

• navigate_page（URL、再読み込み）
• navigate_page_history（戻る／進む）
• wait_for（テキストの表示、条件）

6. マルチタブ管理

複数のページやフレームを操作します。

1. List open pages: list_pages
2. Create new page: new_page url="https://example.com"
3. Switch context: select_page pageIdx=1
4. Close pages: close_page pageIdx=2

フレームの処理：

• 子フレームやワーカーに自動で接続します
• フレームツリー構造を確認します
• ページ遷移後もセッションを維持します

高度なワークフロー

デバイスエミュレーションによるパフォーマンス分析

1. resize_page width=390 height=844 (iPhone 14 Pro)
2. emulate_network throttlingOption="Fast 4G"
3. emulate_cpu throttlingRate=4
4. performance_start_trace reload=true
5. performance_stop_trace
6. performance_analyze_insight insightName="DocumentLatency"

フィルタリングによるネットワーク分析

1. navigate_page url="https://example.com"
2. list_network_requests resourceTypes=["script", "fetch", "xhr"]
3. Filter by: pageSize=100, pageIdx=0, includePreservedRequests=true
4. get_network_request reqid=123 (detailed timing/headers/body)

アクセシビリティテストのパターン

1. navigate_page url="https://example.com"
2. take_snapshot verbose=true (full a11y tree with all properties)
3. Validate: roles, names, ARIA attributes, relationships
4. Test interactions: click, fill, keyboard navigation via UIDs

クロスブラウザーのビューポートテスト

1. Define breakpoints: [320, 768, 1024, 1920]
2. For each breakpoint:
   - resize_page width=X height=Y
   - take_screenshot format="png" quality=90
   - take_snapshot (verify accessibility)
3. Compare layouts and a11y across sizes

ツールの完全なリファレンス

6 つのカテゴリにわたり、27 個のツールを利用できます。

入力の自動化（8）： click、drag、fill、fill_form、handle_dialog、hover、press_key、upload_file

ナビゲーション（7）： close_page、list_pages、navigate_page、navigate_page_history、new_page、select_page、wait_for

エミュレーション（3）： emulate_cpu、emulate_network、resize_page

パフォーマンス（3）： performance_analyze_insight、performance_start_trace、performance_stop_trace

ネットワーク（2）： get_network_request、list_network_requests

デバッグ（4）： evaluate_script、get_console_message、list_console_messages、take_screenshot、take_snapshot

ツールのパラメーターと例について詳しくは、TOOLS.md を参照してください。

ワークフローのパターンについて詳しくは、WORKFLOWS.md を参照してください。

Core Web Vitals のしきい値と測定ガイドについて詳しくは、METRICS.md を参照してください。

設定オプション

接続フラグ

• --browserUrl, -u <string> - 実行中の Chrome インスタンスに接続します（ポートフォワーディング）
• --wsEndpoint, -w <string> - Chrome 接続用の WebSocket エンドポイント
• --wsHeaders <JSON> - 認証が必要な WebSocket 接続用のカスタムヘッダー

ブラウザー設定

• --headless <boolean> - ヘッドレスモードで実行します（デフォルト：false）
• --executablePath, -e <string> - カスタム Chrome 実行ファイルへのパス
• --channel <string> - Chrome チャネル：stable、canary、beta、dev（デフォルト：stable）
• --viewport <string> - 初期ビューポートサイズ（形式：WIDTHxHEIGHT、例：1280x720）

セキュリティと分離

• --isolated <boolean> - 推奨： 一時的な user-data-dir を作成し、自動でクリーンアップします（デフォルト：false）
• --user-data-dir <string> - カスタムユーザーデータディレクトリ
• --acceptInsecureCerts <boolean> - 証明書エラーを無視します（セキュリティリスク。開発／テスト専用）

ネットワーク

• --proxyServer <string> - プロキシサーバーの設定

デバッグ

• --logFile <string> - デバッグログの保存先（詳細なログを有効にするには、DEBUG=* 環境変数を設定します）

その他

• --chromeArg <string> - Chrome に追加する引数（複数指定可能）

すべてのオプションを表示するには、npx chrome-devtools-mcp@latest --help を実行してください。

本番環境の設定例

安全な分離テスト

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--isolated=true",
        "--headless=true",
        "--viewport=1920x1080",
        "--channel=stable"
      ]
    }
  }
}

外部の Chrome インスタンスに接続する

# Launch Chrome with remote debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

# Get WebSocket endpoint
curl http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl'

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>"
      ]
    }
  }
}

ロギングを有効にした本番環境

{
  "mcpServers": {
    "chrome-devtools-prod": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222",
        "--isolated=true",
        "--logFile=/var/log/chrome-devtools-mcp.log"
      ],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

セキュリティに関する考慮事項

データ露出に関する警告

Chrome DevTools MCP 公式のセキュリティ通知：

「chrome-devtools-mcp はブラウザーインスタンスのコンテンツを MCP クライアントに公開し、ブラウザーまたは DevTools 内のあらゆるデータの検査、デバッグ、変更を可能にします。MCP クライアントと共有したくない機密情報や個人情報は共有しないでください。」

ベストプラクティス

1. 機密性の高いワークフローでは分離モードを使用する

   • --isolated=true は一時的なユーザーデータディレクトリを作成します
   • ブラウザーを閉じると自動的にクリーンアップされます
   • セッション間でデータが保持されるのを防ぎます

2. 証明書の取り扱いに注意する

   • --acceptInsecureCerts はセキュリティリスクです
   • 開発／テスト環境でのみ使用してください
   • 機密データを扱う場合は決して使用しないでください

3. ユーザーデータディレクトリを管理する

   • デフォルトのディレクトリはすべてのインスタンス間で共有されます
   • 実行のたびにクリアされるわけではありません
   • Cookie、キャッシュ、閲覧履歴が含まれます
   • 管理するには --isolated またはカスタムの --user-data-dir を使用してください

4. WebSocket 認証

   • 認証が必要な接続には --wsHeaders を使用します
   • 例：--wsHeaders='{"Authorization":"Bearer token"}'
   • --wsEndpoint と併用した場合のみ動作します

技術的な制約

検証済みの制限事項

1. ブラウザーのサポート： Chrome／Chromium のみ（Firefox、Safari、旧版 Edge は対象外です）

2. Node.js の要件： v20.19 以降（最新のメンテナンス LTS）

3. ブラウザーのライフサイクル： ブラウザーは最初のツール使用時に自動起動し、MCP サーバーへの接続時には起動しません

4. デフォルトの永続化： --isolated=true を使用しない限り、ユーザーデータディレクトリは実行間で保持されます

5. 権限の要件：

   • MCP クライアントによっては、macOS のフルディスクアクセスが必要な場合があります
   • Chrome には独自のサンドボックスを作成する権限が必要です
   • MCP クライアントのサンドボックスを無効にするか、外部の Chrome インスタンスを使用する必要がある場合があります

6. スクリーンショットの形式： 初回キャプチャでは指定した形式（JPEG／PNG）を使用し、最終出力では WebP を使用します（使用できない場合は PNG にフォールバックします）

7. ツールの利用可能性： 接続後、27 個すべてのツールをすぐに利用でき、段階的なロック解除はありません

リソースとドキュメント

公式ソース

• GitHub リポジトリ： https://github.com/ChromeDevTools/chrome-devtools-mcp
• npm パッケージ： https://www.npmjs.com/package/chrome-devtools-mcp
• Chrome DevTools Protocol： https://chromedevtools.github.io/devtools-protocol/

Core Web Vitals

• Web Vitals の概要： https://web.dev/articles/vitals
• INP のドキュメント： https://web.dev/articles/inp
• LCP のドキュメント： https://web.dev/articles/lcp
• CLS のドキュメント： https://web.dev/articles/cls
• FID に代わる INP（3 月 12 日）： https://web.dev/blog/inp-cwv-march-12

ツール

• PageSpeed Insights： https://pagespeed.web.dev
• Chrome User Experience Report： https://developer.chrome.com/docs/crux
• Lighthouse のドキュメント： https://developer.chrome.com/docs/lighthouse

関連するスキルファイル

• WORKFLOWS.md - 詳細なワークフローパターンと複数ステップのプロセス
• METRICS.md - Core Web Vitals のしきい値と測定方法の完全なガイド
• TOOLS.md - ツールのパラメーターと使用例に関する包括的なリファレンス

バージョン情報

• MCP サーバーのバージョン： v0.5.1（2025 年 10 月 17 日）
• ツール数： 27 個
• Core Web Vitals の更新： 2024 年 3 月 12 日に INP が FID に取って代わりました
• 現在の指標： INP、LCP、CLS（TBT はラボ環境での代替指標であり、Core Web Vital ではありません）