browsing

Chrome Directでのブラウジング

概要

use_browser MCP ツールを使って、DevTools Protocol 経由で Chrome を操作します。Chrome が自動的に起動する、統合された単一のインターフェースです。

告知: 「Chrome を操作するため、ブラウジングスキルを使用しています。」

使用するタイミング

次の場合に使用します：

• 認証済みのセッションを操作する場合
• 起動中のブラウザーで複数のタブを管理する場合
• Playwright MCP を利用できない場合、または過剰な機能が必要ない場合

次の場合は Playwright MCP を使用します：

• 新しいブラウザーインスタンスが必要な場合
• スクリーンショットや PDF を生成する場合
• より高水準の抽象化を使用したい場合

自動キャプチャ

すべての DOM 操作（navigate、click、type、select、eval、keyboard_press、hover、drag_drop、double_click、right_click、file_upload）で、次のファイルが自動的に保存されます：

• {prefix}.png — ビューポートのスクリーンショット
• {prefix}.md — ページの内容を構造化した Markdown
• {prefix}.html — レンダリング済み DOM 全体
• {prefix}-console.txt — ブラウザーのコンソールメッセージ

ファイルはセッションディレクトリに連番のプレフィックス（001-navigate、002-click など）を付けて保存されます。extract または screenshot 操作を使用する前に、これらのファイルを確認してください。

認証情報に類似した内容を含むページ： ページにトークンやシークレット（Slack の xoxb-／xapp-、GitHub の ghp_／github_pat_、1Password の ops_／A3- キー、otpauth:// シード、または data-sen-secret が設定された要素）が表示されている場合、その操作ではファイルは書き込まれず、メタデータのみを含む ⚠️ Page shows credential-shaped content; auto-capture and DOM output suppressed. という応答が返されます。extract／eval の出力では、そのような値は [REDACTED credential-shaped] に置き換えられ、screenshot は拒否されます。シークレットのキャプチャには認証情報ブローカーを使用してください。eval は値を参照しないクエリ（例：「トークン欄は存在するか？」）にのみ使用してください。チェック対象は HTML、レンダリングされたテキスト、開いたシャドウルートですが、閉じたシャドウルートや iframe は対象外です。SUPERPOWERS_CHROME_ALLOW_CREDENTIAL_CAPTURE=1 を設定すると、この機能は無効になります。

use_browser ツール

アクションベースのインターフェースを持つ単一の MCP ツールです。初回の使用時に Chrome が自動起動します。

パラメーター：

• action（必須）：実行する操作
• selector（任意）：要素操作に使用する CSS または XPath セレクター
• payload（任意）：操作固有のデータ（文字列またはオブジェクト）
• timeout（任意）：待機操作のタイムアウト（ミリ秒、デフォルト：5000）

アクティブなタブ：各操作は現在の activeTab に対して実行されます。タブを切り替えるには switch_tab を使用します。

アクションのリファレンス

ナビゲーション

• navigate：URL に移動します

  • payload：URL 文字列
  • 例：{action: "navigate", payload: "https://example.com"}

• await_element：要素が表示されるまで待機します

  • selector：CSS セレクター
  • timeout：最大待機時間（ミリ秒）
  • 例：{action: "await_element", selector: ".loaded", timeout: 10000}

• await_text：テキストが表示されるまで待機します

  • payload：表示されるのを待つテキスト
  • 例：{action: "await_text", payload: "Welcome"}

操作

• click：要素をクリックします

  • selector：CSS セレクター
  • 例：{action: "click", selector: "button.submit"}

• type：テキストを入力します

  • selector：任意 — 最初にクリックしてフォーカスします
  • payload：入力するテキスト（\t=Tab、\n=Enter）
  • 例：{action: "type", selector: "#email", payload: "[email protected]"}

• double_click：要素をダブルクリックします（dblclick イベントを発生させます）

  • selector：CSS セレクター
  • 例：{action: "double_click", selector: ".item"}

• right_click：要素を右クリックします（contextmenu イベントを発生させます）

  • selector：CSS セレクター
  • 例：{action: "right_click", selector: ".row"}

• select：ドロップダウンの選択肢を選びます

  • selector：CSS セレクター
  • payload：選択肢の値
  • 例：{action: "select", selector: "select[name=state]", payload: "CA"}

• keyboard_press：特殊キー（Tab、Enter、Escape、矢印キー、F1-F12）を押します

  • payload：キー名（文字列）、または {"key": "Tab", "modifiers": {"shift": true, "ctrl": false, "alt": false, "meta": false}}
  • 例：{action: "keyboard_press", payload: "Tab"}
  • 修飾キーを使う例：{action: "keyboard_press", payload: {"key": "Tab", "modifiers": {"shift": true}}}

マウス操作（CDP レベル）

CDP Input.dispatchMouseEvent を使用し、合成イベントの制限を回避します。

• hover：要素の上にマウスを移動します（CSS :hover、ツールチップ、メニュー）

  • selector：CSS セレクター
  • 例：{action: "hover", selector: ".menu-trigger"}

• drag_drop：要素をターゲットにドラッグします（CDP によるネイティブのドラッグ＆ドロップ）

  • selector：ソース要素
  • payload：ターゲットのセレクターまたは JSON 座標 {"x":N,"y":N}
  • 例：{action: "drag_drop", selector: ".card", payload: ".column-2"}

• mouse_move：マウスを座標に移動します

  • payload：JSON {"x":N,"y":N}（滑らかな移動には steps、fromX、fromY を指定できます）
  • 例：{action: "mouse_move", payload: "{\"x\":100,\"y\":200}"}

• scroll：マウスホイールイベントでスクロールします

  • payload：方向（up/down/left/right）または JSON {"deltaX":N,"deltaY":N}
  • selector：省略可 — 要素内をスクロールします
  • 例：{action: "scroll", payload: "down"}

ファイルのアップロード

• file_upload：input[type=file] 要素にファイルを設定します（JavaScript では実行できません）
  • selector：ファイル入力要素
  • payload：ファイルパスまたは JSON {"files":["/path/a.pdf","/path/b.jpg"]}
  • 例：{action: "file_upload", selector: "#upload", payload: "/tmp/doc.pdf"}

抽出

• extract：ページのコンテンツを取得します

  • payload：形式（'markdown'|'text'|'html'）
  • selector：省略可 - 対象を要素に限定します
  • 例：{action: "extract", payload: "markdown"}
  • 例：{action: "extract", payload: "text", selector: "h1"}

• attr：要素の属性を取得します

  • selector：CSS セレクター
  • payload：属性名
  • 例：{action: "attr", selector: "a.download", payload: "href"}

• eval：JavaScript を実行します

  • payload：JavaScript コード
  • 例：{action: "eval", payload: "document.title"}

エクスポート

• screenshot：特定の要素のスクリーンショットを撮影します
  • payload：ファイル名
  • selector：省略可 - 特定の要素のスクリーンショットを撮影します
  • ビューポートのスクリーンショットは、DOM 操作のたびに自動で撮影されます。特定の要素が必要な場合にのみ使用してください。
  • 例：{action: "screenshot", payload: "/tmp/chart.png", selector: ".chart"}

タブ管理

• list_tabs：開いているすべてのタブを一覧表示します

  • 例：{action: "list_tabs"}

• new_tab：新しいタブを作成します

  • 例：{action: "new_tab"}

• close_tab：アクティブなタブを閉じます

  • 例：{action: "close_tab"}

• switch_tab：アクティブなタブを切り替えます（固定 — 変更するまで維持されます）

  • payload：タブのインデックス（数値）、URL の一部、またはタイトルの一部
  • 例：{action: "switch_tab", payload: 1}（インデックスで指定）
  • 例：{action: "switch_tab", payload: "example.com"}（URL の一部で指定）
  • 例：{action: "switch_tab", payload: "GitHub"}（タイトルの一部で指定）

ブラウザモードの制御

• show_browser：ブラウザウィンドウを表示します（ヘッドありモード）

  • 例：{action: "show_browser"}
  • ⚠️ 警告：Chrome を再起動し、GET でページを再読み込みするため、POST の状態は失われます

• hide_browser：ヘッドレスモードに切り替えます（ブラウザは非表示）

  • 例：{action: "hide_browser"}
  • ⚠️ 警告：Chrome を再起動し、GET でページを再読み込みするため、POST の状態は失われます

• browser_mode：現在のブラウザモード、ポート、プロファイルを確認します

  • 例：{action: "browser_mode"}
  • 返り値：{"headless": true|false, "mode": "headless"|"headed", "running": true|false, "port": 9222, "profile": "name", "profileDir": "/path"}

プロファイル管理

• set_profile：Chrome のプロファイルを変更します（先に Chrome を終了する必要があります）

  • 例：{action: "set_profile", "payload": "browser-user"}
  • ⚠️ 警告：先に Chrome を停止する必要があります
  • 副作用：プロファイルを明示的に指定した状態にし、自動判別の対象外になります（以下を参照）

• get_profile：現在のプロファイル名とディレクトリを取得します

  • 例：{action: "get_profile"}
  • 戻り値：{"profile": "name", "profileDir": "/path"}

デフォルトの動作：Chrome はヘッドレスモードで、「superpowers-chrome」プロファイルを使用し、動的に割り当てられたポート（範囲：9222～12111）で起動します。ポートは CHROME_WS_PORT で、プロファイルは CHROME_WS_PROFILE で上書きできます。

複数の MCP 間での自動判別： 同じホスト上で 2 つの MCP サーバーがデフォルトのプロファイルを使用して起動すると、最初のサーバーが superpowers-chrome（ポート 9222）を確保し、後続のサーバーは通知なく superpowers-chrome-2（ポート 9223）、superpowers-chrome-3 などに切り替わります。各 MCP はそれぞれ専用のプロファイルディレクトリで独自の Chrome を操作するため、activeTab を奪い合うことはありません。ブリッジは ~/.cache/superpowers/browser-profiles/<profile>.mcp.lock のロックファイルで所有権を管理します。古いロック（PID が終了済みのもの）は自動的に解放されます。

自動判別を無効にするには（たとえば、長時間実行する chrome-ws CLI セッションと MCP の間で意図的に Chrome を共有する場合）、プロファイル名を明示的に設定します。

• 環境変数：CHROME_WS_PROFILE=my-profile
• または、実行時に {action: "set_profile", payload: "my-profile"} を指定します

プロファイル名を明示的に指定した場合もロックは取得しますが、競合時にブリッジは自動判別せず、共有します。2 つ目のプロセスは 1 つ目の Chrome に再接続します（従来の再起動時再接続の動作）。

Chrome のライフサイクル（復旧）

• kill_chrome：この MCP が操作している Chrome プロセスを終了します

  • 例：{action: "kill_chrome"}
  • meta.json を解放します。次のページ操作時に Chrome が自動的に再起動します

• restart_chrome：kill_chrome の実行後、直ちに起動します

  • 例：{action: "restart_chrome"}

自動再起動バナー：ブリッジが新しい Chrome を起動する必要がある場合（以前のプロセスが終了した場合や、シェルから kill -9 <pid> を実行するなどして外部から強制終了された場合）、再起動後の最初の応答には次の内容が先頭に追加されます。

[Chrome auto-restarted; URL reset to about:blank. Re-navigate to continue.]

これは以前の URL やタブの状態が失われたことを示しています。現在のページについて判断する前に、改めて移動してください。

コンソールログ

アクティブなタブのブラウザーコンソール出力を記録します。バッファーはページセッションの sessionId によって管理されるため、close_tab／new_tab の実行順序に関する問題が起きても保持されます。レベル：log、info、warn、error。

• enable_console_logging：記録を開始します

  • 例：{action: "enable_console_logging"}

• get_console_messages：記録されたメッセージを読み取ります

  • すべて：{action: "get_console_messages"}
  • 指定したタイムスタンプ以降（エポックミリ秒）：{action: "get_console_messages", payload: {since: 1716000000000}}
  • 戻り値：{timestamp, level, text} エントリーの配列

• clear_console_messages：バッファーをリセットします

  • 例：{action: "clear_console_messages"}

ダイアログの処理

ネイティブダイアログ（JS の alert／confirm／prompt、beforeunload、HTTP 基本認証、権限プロンプト、デバイス選択ダイアログ）がページを一時停止させます。ダイアログが開いている間、ページを対象とするアクション（extract、click、eval など）は、Page is behind a dialog を含むテキストと、使用可能な dialog::* セレクターの一覧を返して拒否されます。

navigate の実行中にダイアログが表示された場合（HTTP 基本認証でよく発生します）、navigate 自体がメッセージ内にダイアログの文法を含むエラーをスローします。ダイアログを検出するために、別途ページを対象とする呼び出しを行う必要はありません。

dialog::* セレクターをクリックまたは入力してダイアログを処理します。

• {action: "click", selector: "dialog::accept"} — JS の alert／confirm／prompt、beforeunload、権限の許可を受け入れます
• {action: "click", selector: "dialog::dismiss"} — 閉じる／キャンセルする／拒否します
• {action: "type", selector: "dialog::prompt", payload: "text"} の後に受け入れます — JS の prompt に応答します
• {action: "type", selector: "dialog::username", payload: "alice"} ＋ {action: "type", selector: "dialog::password", payload: "secret"} ＋ {action: "click", selector: "dialog::accept"} — HTTP 基本認証
• {action: "click", selector: "dialog::device[id=\"<deviceId>\"]"} — WebUSB／Bluetooth／Serial／HID デバイスを選択します

モード切り替え時の重要な注意事項：

1. Chrome の再起動が必要です — 起動中の Chrome ではヘッドレスモードとヘッド付きモードを切り替えられません
2. ページは GET で再読み込みされます — 開いているすべてのタブが GET リクエストで再度開かれます
3. POST の状態は失われます — フォーム送信、POST の結果、POST ベースのナビゲーションは失われます
4. セッションの状態は失われます — JavaScript 変数など、クライアント側の状態はすべてクリアされます
5. Cookie／認証情報は保持される場合があります — 同じユーザーデータディレクトリを使うため、ログイン済みセッションが維持されることがあります

ヘッド付きモードを使う場合：

• 視覚的なレンダリングの問題をデバッグするとき
• ブラウザーの動作をユーザーに実演するとき
• ブラウザーを表示した状態でのみ動作する機能をテストするとき
• ヘッドレスモードでは再現しない問題をデバッグするとき

ヘッドレスモードを使用し続ける場合（デフォルト）：

• その他すべての場合 — より高速で、すっきりしており、影響も少なくなります
• スクリーンショットはヘッドレスモードでも問題なく動作します
• ほとんどの自動化は、どちらのモードでも同じように動作します

プロファイル管理： プロファイルには永続的なブラウザーデータ（Cookie、localStorage、拡張機能、認証セッション）が保存されます。

プロファイルの保存場所：

• macOS：~/Library/Caches/superpowers/browser-profiles/{name}/
• Linux：~/.cache/superpowers/browser-profiles/{name}/
• Windows：%LOCALAPPDATA%/superpowers/browser-profiles/{name}/

プロファイルを分けて使う場合：

• デフォルトのプロファイル（"superpowers-chrome"）：一般的な自動化、共有セッション
• エージェントごとのプロファイル：各エージェントのブラウザー状態を分離します
  • 例：browser-user エージェントは "browser-user" プロファイルを使用します
• タスクごとのプロファイル：異なるユーザーコンテキストでテストします
  • 例："test-logged-in" と "test-logged-out"

プロファイルデータは次の後も保持されます：

• Chrome の再起動
• モードの切り替え（ヘッドレス ↔ ヘッド付き）
• システムの再起動（データはキャッシュディレクトリに保存されています）

別のプロファイルを使う方法：

1. Chrome が起動している場合は終了します：await chromeLib.killChrome()
2. プロファイルを設定します：{action: "set_profile", "payload": "my-profile"}
3. Chrome を起動します：次の navigate／action で新しいプロファイルが使われます

クイックスタートのパターン

Navigate and extract:
{action: "navigate", payload: "https://example.com"}
{action: "await_element", selector: "h1"}
{action: "extract", payload: "text", selector: "h1"}

よく使うパターン

フォームへの入力と送信

{action: "navigate", payload: "https://example.com/login"}
{action: "await_element", selector: "input[name=email]"}
{action: "type", selector: "input[name=email]", payload: "[email protected]"}
{action: "type", selector: "input[name=password]", payload: "pass123"}
{action: "keyboard_press", payload: "Enter"}
{action: "await_text", payload: "Welcome"}

フォームの送信には keyboard_press を使用します。

複数タブのワークフロー

{action: "list_tabs"}
{action: "switch_tab", payload: 2}
{action: "click", selector: "a.email"}
{action: "await_element", selector: ".content"}
{action: "extract", payload: "text", selector: ".amount"}

動的コンテンツ

{action: "navigate", payload: "https://example.com"}
{action: "type", selector: "input[name=q]", payload: "query"}
{action: "click", selector: "button.search"}
{action: "await_element", selector: ".results"}
{action: "extract", payload: "text", selector: ".result-title"}

リンク属性の取得

{action: "navigate", payload: "https://example.com"}
{action: "await_element", selector: "a.download"}
{action: "attr", selector: "a.download", payload: "href"}

JavaScript の実行

{action: "eval", payload: "document.querySelectorAll('a').length"}
{action: "eval", payload: "Array.from(document.querySelectorAll('a')).map(a => a.href)"}

ビューポートのサイズ変更（レスポンシブテスト）

レスポンシブレイアウトのテストでは、eval を使ってブラウザーウィンドウのサイズを変更します。

{action: "eval", payload: "window.resizeTo(375, 812); 'Resized to mobile'"}
{action: "eval", payload: "window.resizeTo(768, 1024); 'Resized to tablet'"}
{action: "eval", payload: "window.resizeTo(1920, 1080); 'Resized to desktop'"}

注意：これはウィンドウのサイズを変更するもので、デバイスエミュレーションではありません。次の項目は変更されません。

• デバイスのピクセル比（Retina ディスプレイ）
• タッチイベント
• User-Agent 文字列

ほとんどのレスポンシブテストでは、ウィンドウのサイズ変更で十分です。

Cookie をクリアする

JavaScript からアクセス可能な Cookie をクリアするには、eval を使用します。

{action: "eval", payload: "document.cookie.split(';').forEach(c => { document.cookie = c.trim().split('=')[0] + '=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/'; }); 'Cookies cleared'"}

注：JavaScript からアクセス可能な Cookie がクリアされます。次の Cookie はクリアされません。

• httpOnly Cookie（サーバー側のみ）
• 他のドメインの Cookie

ほとんどのログアウト／リセットのケースでは、これで十分です。

ページをスクロールする

{action: "scroll", payload: "down"}
{action: "scroll", payload: "up"}
{action: "scroll", selector: ".container", payload: "{\"deltaX\":0,\"deltaY\":500}"}

実際のマウスホイールイベントを使用します（eval と scrollTo の組み合わせはボット検出ツールに検知されます）。

ヒント

操作の前に必ず待機する： ページを移動した直後にクリックや入力を行わないでください。ページの読み込みには時間がかかります。

// BAD - might fail if page slow
{action: "navigate", payload: "https://example.com"}
{action: "click", selector: "button"}  // May fail!

// GOOD - wait first
{action: "navigate", payload: "https://example.com"}
{action: "await_element", selector: "button"}
{action: "click", selector: "button"}

具体的なセレクターを使用する： 複数の要素に一致する汎用的なセレクターは避けてください。

// BAD - matches first button
{action: "click", selector: "button"}

// GOOD - specific
{action: "click", selector: "button[type=submit]"}
{action: "click", selector: "#login-button"}

フォームを送信する： type の後に keyboard_press で Enter キーを押すか、ペイロードに \n を追加してください。

{action: "type", selector: "#search", payload: "query"}
{action: "keyboard_press", payload: "Enter"}

まずコンテンツを確認する： ワークフローを作成する前にページのコンテンツを抽出し、セレクターを確認してください。

{action: "extract", payload: "html"}

トラブルシューティング

要素が見つからない：

• 操作の前に await_element を使用する
• 'html' 形式の extract アクションを使ってセレクターを確認する

タイムアウトエラー：

• 読み込みの遅いページではタイムアウトを延長する：{timeout: 30000}
• テキストではなく、特定の要素を待機する

アクティブなタブが違う：

• list_tabs を使用して開いているタブをすべて確認する
• URL またはタイトルの部分文字列を指定して switch_tab を使用すると、確実にタブを切り替えられます
• タブを閉じるとタブのインデックスが変わるため、URL／タイトルによる切り替えを優先する

eval が [object Object] を返す：

• 複雑なオブジェクトには JSON.stringify() を使用する：{action: "eval", payload: "JSON.stringify({name: 'test'})"}
• 非同期関数の場合：{action: "eval", payload: "JSON.stringify(await yourAsyncFunction())"}

テスト自動化（上級）

{"action": "navigate", "payload": "https://app.com"}
{"action": "click", "selector": "#test-button"}
{"action": "eval", "payload": "JSON.stringify({passed: document.querySelector('.success') !== null})"}

# Example: Automated form testing
./chrome-ws navigate 0 "https://app.com/form"
./chrome-ws fill 0 "#email" "[email protected]"
./chrome-ws click 0 "button[type=submit]"
./chrome-ws wait-text 0 "Success"

高度な使用方法

Claude Code の外部でコマンドラインを使用する方法については、COMMANDLINE-USAGE.md を参照してください。

詳しい例については、EXAMPLES.md を参照してください。

プロトコルのリファレンス

CDP の全ドキュメント：https://chromedevtools.github.io/devtools-protocol/