faster-chrome-devtools-skill

より高速な Chrome DevTools：CDP 直接接続

付属の CLI を使って、Chrome DevTools Protocol （CDP）経由で Chrome を操作します。Node.js の組み込み機能を使い、Chrome のブラウザー WebSocket に直接接続します。 MCP サーバー、Puppeteer のインストール、Playwright のインストール、パッケージのインストールは不要です。

node <skill-directory>/scripts/cdp.mjs --help

<skill-directory> を、この SKILL.md が含まれるディレクトリに置き換えてください。 Node.js 22 以降が必要です。

接続前

ローカルの Chrome にアクセスすると、ユーザーが開いているタブやログイン済みのブラウザー状態が公開されます。 ブラウザーを調べたり操作したりする前に、ユーザーの承認を得てください。 リモートデバッグがまだ有効でない場合は、chrome://inspect/#remote-debugging で有効にするようユーザーに依頼してください。Chrome に デバッグを許可 の確認プロンプトが表示される場合もあります。

ログイン状態のないクリーンなセッションを使う場合は、ユーザーの Chrome ではなく、ローカルで別の匿名 Chrome を起動する（「匿名のローカル Chrome」を参照）か、リモートブラウザーに接続してください。

接続

CLI は次の接続方法を順に試します。

1. --ws-endpoint または CDP_WS_ENDPOINT
2. --http-endpoint または CDP_HTTP_ENDPOINT。/json/version を使って検出します
3. macOS、Windows、Linux 上の Chrome の DevToolsActivePort ファイル
4. http://127.0.0.1:9222/json/version

例：

# Discover a local Chrome automatically
node <skill-directory>/scripts/cdp.mjs list

# Discover through an HTTP debugging port
node <skill-directory>/scripts/cdp.mjs \
  --http-endpoint http://127.0.0.1:9222 list

# Connect directly to a local or remote browser WebSocket
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint 'wss://browser.example/devtools/browser/...' list

# Authenticated remote endpoint
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint "$CDP_WS_ENDPOINT" \
  --headers '{"Authorization":"Bearer ..."}' list

認証情報がシェルの履歴に残らないよう、シークレットには環境変数を使ってください。

export CDP_WS_ENDPOINT='wss://...'
export CDP_HEADERS='{"Authorization":"Bearer ..."}'
node <skill-directory>/scripts/cdp.mjs list

匿名のローカル Chrome

ユーザーのブラウザーではなく、ログイン状態のないクリーンなインスタンスを使うには、使い捨てのプロファイルでリモートデバッグを有効にした別の Chrome を起動し、そのポートに接続します。デフォルト以外の --user-data-dir が必要です（Chrome 136 以降では、デフォルトのプロファイルでデバッグポートを使用できません）。また、これによりユーザーのセッションからインスタンスが分離されます。

nohup "$CHROME" --remote-debugging-port=9333 --user-data-dir="$(mktemp -d)" \
  --no-first-run --no-default-browser-check about:blank >/dev/null 2>&1 &
node <skill-directory>/scripts/cdp.mjs --http-endpoint http://127.0.0.1:9333 list

$CHROME は Chrome または Chromium のバイナリです。たとえば macOS では /Applications/Google Chrome.app/Contents/MacOS/Google Chrome、Linux では google-chrome です。9333 が使用中の場合は、空いているポートを選んでください。起動コマンドが戻った直後にブラウザーが終了する場合は、デタッチして起動してください（macOS の場合：open -na "Google Chrome" --args --remote-debugging-port=9333 --user-data-dir=<dir> about:blank）。

バックグラウンドデーモンは、最後のコマンドの実行後もブラウザー接続を 20 分間維持します。これにより、接続の再確立や Chrome の承認プロンプトの再表示を避けられます。作業が終わったら、明示的に停止してください。

# Stops the daemon when exactly one is running; no browser discovery is needed
node <skill-directory>/scripts/cdp.mjs stop

# Select one when several endpoints have active daemons
node <skill-directory>/scripts/cdp.mjs stop --id <daemon-id>

# Stop only the daemon created for this endpoint, without reconnecting to it
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint 'wss://browser.example/devtools/browser/...' stop

# Deliberately stop every daemon
node <skill-directory>/scripts/cdp.mjs stop --all

通常の stop は、複数のデーモンが稼働中の場合、停止を拒否して安全な ID とホストを表示します。エンドポイントのクエリー文字列や認証ヘッダーは表示しません。

基本的な操作の流れ

まずページを一覧表示します。各コマンドには、この出力に含まれる一意なターゲット ID のプレフィックスを指定します。

node <skill-directory>/scripts/cdp.mjs list
node <skill-directory>/scripts/cdp.mjs snapshot <target>

アクセシビリティスナップショットを使ってページの状態を確認します。操作可能なノードには ref=123 のような安定したバックエンド DOM 参照が含まれています。これらは ref:123 として指定します。

node <skill-directory>/scripts/cdp.mjs click <target> ref:123
node <skill-directory>/scripts/cdp.mjs wait-for <target> text 'Sign in' 5000
node <skill-directory>/scripts/cdp.mjs fill <target> ref:456 '[email protected]'
node <skill-directory>/scripts/cdp.mjs press <target> Enter
node <skill-directory>/scripts/cdp.mjs wait-for <target> text 'Welcome' 10000

スナップショットの参照が利用できない場合は、CSS セレクターを使えます。

node <skill-directory>/scripts/cdp.mjs click <target> 'button[type=submit]'
node <skill-directory>/scripts/cdp.mjs fill <target> 'input[name=email]' '[email protected]'

状態が変化するたびに wait-for で確認してください。任意の待機時間を追加しないでください。 wait-for は MutationObserver を使い、期待するテキストまたはセレクターがすでに存在する場合は直ちに完了します。

コマンドリファレンス

list
open [url]
snapshot <target>
screenshot <target> [file] [--format jpeg|webp|png] [--quality 75] [--full-page]
navigate <target> <url> [timeout-ms]
evaluate <target> <expression>
html <target> [selector]
click <target> <selector|ref:123>
fill <target> <selector|ref:123> <value>
type <target> <text>
press <target> <key>
wait-for <target> <text|selector> <value> [timeout-ms]
live-view <target> [expires-ms]
handoff <target> <instructions> [timeout-ms]
handoff-state <target>
console <target>
failures <target>
raw <target> <CDP.method> [json-params]
stop [--id <daemon-id> | --all]

グローバルオプションは、コマンドの前に指定する必要があります。

--ws-endpoint <ws://...>
--http-endpoint <http://...>
--headers <json>
--timeout <ms>

JavaScript から要素にアクセスできない場合（クロスオリジン iframe 内の入力欄など）は、要素にフォーカスした後で type を使います。DOM の評価ではなく、CDP の Input.insertText を使います。

プロトコルメソッドを自由に実行するための手段として、raw を使います。

node <skill-directory>/scripts/cdp.mjs raw <target> DOM.getDocument '{}'

スクリーンショットの前にスナップショットを使う

ページの状態を把握したり操作したりするには、snapshot を使います。こちらのほうが高速で、テキストと要素参照が得られます。スクリーンショットは、CSS の描画、画像、キャンバス、グラフ、レイアウトなど、見た目が重要な場合にのみ screenshot を使ってください。

スクリーンショットはデフォルトで JPEG 品質 75 でファイルに保存されるため、大きなインライン Base64 ペイロードを避けられます。PNG は可逆圧縮ですが、ファイルサイズがかなり大きくなることがよくあります。ページ全体の画像も負荷が大きくなる可能性があるため、必要な場合にのみ使ってください。

# Safe default: viewport JPEG at quality 75
node <skill-directory>/scripts/cdp.mjs screenshot <target> /tmp/page.jpg

# Full page, still compressed
node <skill-directory>/scripts/cdp.mjs screenshot <target> /tmp/page.webp \
  --format webp --quality 75 --full-page

ページ全体の PNG は避けてください。数 MB に達することが多く、その後に添付するとモデルのコンテキストを消費します。

ナビゲーションと待機

すべてのプロトコル呼び出しのデフォルトのタイムアウトは15秒です。ブラウザー操作がいつまでも終わらない状態を避けるため、ナビゲーションには現実的なタイムアウトを設定してください。

node <skill-directory>/scripts/cdp.mjs navigate <target> \
  https://example.com 15000

推奨される上限：

コンテキスト	タイムアウト
ローカル開発サーバー	10,000ms
通常のWebページ	15,000ms
リソースを多く使用するページ	30,000ms
OAuthまたは外部リダイレクト	60,000ms

navigate は document.readyState === "complete" になるまで待機します。動的なアプリケーションの状態はその後に反映される場合があるため、ナビゲーションの後に wait-for または snapshot を実行してください。

デバッグ

DevToolsを開かずに、キャプチャされたコンソール出力と失敗したネットワーク読み込みを確認します。

node <skill-directory>/scripts/cdp.mjs console <target>
node <skill-directory>/scripts/cdp.mjs failures <target>

メッセージは、デーモンがそのページに初めて接続した後にキャプチャされます。最初の結果が空の場合は、ページコマンドを実行してから問題を再現してください。

evaluate を使用してアプリケーションの状態を調べたり、カスタムコントロールを操作したりできます。

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  '({url: location.href, state: document.querySelector(".status")?.dataset.state})'

DOMが変化する可能性がある場合、別々のコマンド間でインデックスベースのセレクターを使用しないでください。スナップショットの参照、安定したCSSセレクター、または必要なデータをすべて取得する1つの評価処理を優先してください。

トラブルシューティング

ブラウザーが見つからない

chrome://inspect/#remote-debugging でリモートデバッグを有効にし、Chromeから求められた場合はアクセスを許可してから、もう一度試してください。Chromeが特定のデバッグポートを指定して起動されている場合は、--http-endpoint http://127.0.0.1:<port> を渡してください。

同じ接続エラーを繰り返し試さないでください。通常はユーザーの操作、または正しいエンドポイントへの修正が必要です。

古いターゲット

タブが閉じたり、新しいターゲットに再読み込みされたりすることがあります。もう一度 list を実行し、現在の一意なプレフィックスを使用してください。

操作の参照先が解決できなくなった

スナップショットの参照先は現在のDOMに対応しています。大きなナビゲーションや再レンダリングの後には、もう一度スナップショットを取得してください。

カスタムUIで入力やクリックが機能しない

安定したCSSセレクター、evaluate、または click でフォーカスしてから type を使う方法を試してください。一部のReactコントロールでは、ネイティブセッターと合成 input／change イベントが必要です。通常の入力欄やテキストエリアでは、fill がすでにこの一連の処理を実行します。

リモートのCloudflare Browser Run

同じCLIで、Cloudflare Browser RunのCDP WebSocketに直接接続できます。そのサービスが提供するエンドポイントと認証ヘッダーを渡してください。MCPプロセスは関与しません。

セットアップ

アカウント ID と API トークンから作成した、CLI が読み取る 2 つの環境変数を設定してから、任意のコマンドを実行します。

export CLOUDFLARE_ACCOUNT_ID=<account-id>
export CLOUDFLARE_API_TOKEN=<token>   # needs Browser Rendering: Edit
export CDP_WS_ENDPOINT="wss://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/browser-run/devtools/browser?keep_alive=600000&lab=true"
export CDP_HEADERS="{\"Authorization\":\"Bearer $CLOUDFLARE_API_TOKEN\"}"
node <skill-directory>/scripts/cdp.mjs list

ユーザーから Cloudflare Browser Run を使うよう求められた場合は、ローカルの Chrome にフォールバックせず、Browser Run を使用します。CDP_WS_ENDPOINT と CDP_HEADERS が設定されていない場合は、CLOUDFLARE_ACCOUNT_ID と CLOUDFLARE_API_TOKEN が設定されているかを確認し、それらから CLI 用の変数を作成します。どちらの組も利用できない場合は、変数が設定されるまで Browser Run を起動できないことをユーザーに伝え、処理を停止します。ユーザーがフォールバックを承認するか、ローカルブラウザーの自動操作を明示的に依頼しない限り、ローカルの Chrome を既定で使用してはいけません。デバッグ中にトークンの値を表示してはいけません。

lab=true を指定すると、Browser Run の実験的な Chrome ベータプールが選択されます。WebMCP を含むベータ版ブラウザーの機能を利用できるよう、Browser Run の使用時は既定で有効にしておきます。本番ワークロードなど、ベータ機能へのアクセスより安定版 Chrome プールの利用を優先する場合に限り、lab=true を削除します。

CLI が読み取るのは CDP_WS_ENDPOINT と CDP_HEADERS のみです。CLOUDFLARE_ACCOUNT_ID と CLOUDFLARE_API_TOKEN は、それらを作成するための入力値にすぎません。シェルセッションごとに環境変数をエクスポートするか、ローカルの .env から読み込んでください（依存関係のない CLI 自体は .env を読み取りません）。トークンがシェルの履歴やプロセス引数に記録されるため、コマンドラインで --headers を渡すのは避けてください。

トークンを作成するには、Cloudflare ダッシュボードを開き、Profile > API Tokens に移動して、Create Token を選択します。提示されている場合は Browser Rendering テンプレートを選択するか、アカウントを対象範囲として Browser Rendering: Edit 権限を持つカスタムトークンを作成します。シークレットは一度だけコピーできます。アカウント ID はアカウントのホームページに表示されます。

Cloudflare が 10000 Authentication error を返す場合、トークンが設定されていないか、無効であるか、Browser Rendering へのアクセス権がありません。ユーザーに Browser Rendering: Edit 権限を持つトークンを作成し、CLOUDFLARE_API_TOKEN を設定するよう依頼してください。トークンの値を表示してはいけません。

人間による介入

自動操作が MFA、SSO、CAPTCHA、機密データの入力、単発の複雑な操作、または人間の承認が必要な操作に達した場合は、構造化されたハンドオフを使用します。これは Browser Run でのみ利用でき、ローカルの Chrome では利用できません。

まず、Live View URL を生成します。有効期限は既定で 10 分です。ハンドオフの予定時間以上の有効期限を設定してください。

node <skill-directory>/scripts/cdp.mjs live-view <target> 600000

返された URL は、一時的なブラウザーアクセス認証情報として扱います。人間のオペレーターにのみ共有してください。ハンドオフを開始する前に、オペレーターに URL を開いてもらい、ページが表示されていることを確認してください。その後、次を実行します。

node <skill-directory>/scripts/cdp.mjs handoff <target> \
  'Please complete MFA, then select Done. Select Failed if you cannot continue.' \
  600000

このコマンドは Cloudflare.handoff を呼び出す前に Cloudflare.handoffComplete をサブスクライブし、オペレーターが Done または Failed を選択するか、ハンドオフがタイムアウトするまで処理をブロックします。タイムアウトの既定値は 10 分で、Cloudflare の上限である 30 分を超えることはできません。自動操作を再開する前に、JSON 結果の success フィールドと reason フィールドを確認し、その後 snapshot を実行して新しいページの状態を検証してください。ページ遷移だけを根拠に成功したと判断してはいけません。

すでにハンドオフが実行中の可能性がある場合は、別のハンドオフを開始する前に確認してください。

node <skill-directory>/scripts/cdp.mjs handoff-state <target>

何を行い、いつ Done または Failed を選択するかを明記した、具体的で実行可能な指示を提示してください。人間が操作しても Browser Run のボットとしての識別情報は隠されないため、サイトによっては引き続きセッションがブロックされる場合があります。Done または Failed の構造化された操作を伴わない手動フローでは、live-view を共有し、wait-for を使って想定されるページ状態を検出します。

WebMCP とベータ版ブラウザー機能

Browser Run のラボセッションでは、Chrome のベータ版機能を利用できます。WebMCP 対応サイトは、document.modelContext を通じて構造化ツールを公開できます。これは、スクリーンショット、クリック、入力を繰り返す方法よりも高速で、壊れにくい場合があります。

ページに移動した後、WebMCP ツールが公開されているか確認します。

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  'document.modelContext?.listTools?.() ?? []'

関連するツールがある場合は、DOM 操作よりもそのツールを優先し、パラメーターを JSON として渡します。

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  '(async () => await document.modelContext.executeTool("tool_name", JSON.stringify({})))()'

ページの状態によって利用可能なツールが変わることがあるため、移動後やツール呼び出し後にツールを再度一覧表示します。関連する WebMCP ツールがない場合は、通常の CDP 操作にフォールバックします。機密性の高い操作では、完了前に人間による確認を求めて一時停止するツールもあります。

クリーンな匿名セッション、CI の実行、またはユーザーの実際のブラウザーからの分離が必要な場合は、リモートブラウザーを優先します。ユーザーの既存のログイン状態が必要な場合や、ユーザーが表示しているタブそのものをデバッグする場合は、ローカルの Chrome を優先します。

Cloudflare Worker 内で、スクリーンショット、PDF、Markdown 抽出、スクレイピング、アクセシビリティツリー（quickAction("accessibilityTree", ...)）など、ステートレスな出力を一度だけ取得する場合は、Browser Rendering バインディングの env.BROWSER.quickAction(...) を優先します。これにより、操作用の参照を含まない、ロール／名前／状態のプレーンなツリーが返されるため、クリック、入力、待機を繰り返すのではなく、「このページの構造を説明する」という一度きりの呼び出しに適しています。複数ステップの移動、ページの変更、デバッグには、インタラクティブな CDP セッションの開始がより適しています。この場合は、後続の click／fill コマンドで使える安定した ref=123 ハンドルを含むアクセシビリティツリーを取得するため、このスキル独自の snapshot コマンドを使用してください。

MCP 互換機能（任意）

環境ですでに Chrome DevTools MCP ツールが公開されている場合は、それらを引き続き使用できます。同じ基本方針が適用されます。スクリーンショットの前にスナップショットを取得し、タブを再利用し、移動時のタイムアウトを設定し、状態の遷移を待ちます。MCP は互換性のための手段であり、このスキルに必須ではありません。

CLI の代替として MCP を使用する方法については、こちらのブログ記事を参照してください：https://github.com/zeke/zeke.sikelianos.com/blob/abb5b6b1d3c1f1a9beeb76d652f8de6dcda92b05/content/browsers-in-the-cloud/index.md