playwright-mcp

Playwright MCP によるブラウザー自動化

Playwright MCP サーバーを使ったリアルタイムのブラウザー操作に精通しています。このスキルでは、直接ブラウザーを操作して、ページの移動、要素の確認、フォームへの入力、Web UI のデバッグを行う方法を説明します。

重要：これは直接のツール呼び出しです

MCP ツールは、Read、Grep、Bash とまったく同じ直接のツール呼び出しです。CLI コマンドではありません。

正しい — ツールを直接呼び出します：

Tool: mcp__playwright__browser_navigate
Parameters: { "url": "http://localhost:3010" }

誤り — シェル経由で呼び出してはいけません：

Bash: claude mcp call playwright browser_navigate ...  # This does not work

Playwright MCP ツールはすべて mcp__playwright__ プレフィックスを使用します。

重要：操作する前に必ずスナップショットを取得します

browser_snapshot は、すべての操作可能な要素の ref 値を含むアクセシビリティツリーを返します。クリック、入力、ホバーの前に、必ずスナップショットを取得してください。すべての操作ツールで ref 値が必要です。

重要：出力サイズに注意します

ツール	出力サイズ	備考
browser_snapshot	中～大	ページの複雑さに応じて大きくなる、完全なアクセシビリティツリー
browser_take_screenshot	大	Base64 画像 — 必要な場合にのみ使用
browser_console_messages	可変	ノイズの多いアプリでは非常に大きくなる場合があります
browser_network_requests	可変	API 呼び出しの多いページでは非常に大きくなる場合があります
browser_navigate	小	ページタイトルのみを返します
browser_click	小	クリック後のスナップショットを返します
browser_type	小	入力後のスナップショットを返します

ページ構造を把握するには、browser_take_screenshot より browser_snapshot を優先してください。スクリーンショットは見た目の確認にのみ使用します。

ワークフロー 1：移動と確認

トリガー： ユーザーが「このページを開いて」「ページに何がある？」「UI を調べて」「レイアウトを確認して」と言ったとき

手順

1. ページに移動します：

   browser_navigate({ url: "http://localhost:3010/home/team-slug/settings" })
   

2. ページ構造を取得します（操作する前に必ず実行します）：

   browser_snapshot → accessibility tree with ref values for all elements
   

3. スナップショットを分析します： ref 値を使って、操作可能な要素（ボタン、リンク、入力欄）を特定します。ページ構造をユーザーに報告します。

判断：スナップショットとスクリーンショットの使い分け

必要なこと	使用するもの
ページ構造の把握、要素の検索	browser_snapshot（構造化されており、ref 値を含む）
見た目、レイアウトの不具合、CSS の問題	browser_take_screenshot（視覚的な画像）
構造と見た目の両方	まずスナップショットを取得し、見た目の確認が必要であれば次にスクリーンショットを取得

ワークフロー 2：フォーム操作

トリガー： ユーザーが「フォームに入力して」「ログインを送信して」「フィールドに入力して」「オプションを選択して」と言ったとき

手順

1. スナップショットを取得してフォーム欄を探します：

   browser_snapshot → identify input refs and their labels
   

2. フィールドに入力します（複雑さに応じて選択します）：

   • 単一フィールド： browser_type({ ref: "input-ref", text: "value" })
   • 複数フィールド： browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] })
   • ドロップダウン： browser_select_option({ ref: "select-ref", values: ["option-value"] })

3. フォームを送信します：

   browser_click({ ref: "submit-button-ref" })
   

4. 結果を確認します：

   browser_snapshot → check for success message, error states, or navigation
   

主なパターン

• 複数フィールドのフォームでは、複数回 browser_type を呼び出すより browser_fill_form のほうが高速です
• 送信ボタンをクリックする代わりに、browser_press_key({ key: "Enter" }) を使用できます
• 送信後、必要であれば待機します：browser_wait_for({ text: "Success" }) を実行してからスナップショットを取得します

ワークフロー 3：デバッグ調査

トリガー： ユーザーが「ページをデバッグして」「エラーを確認して」「どんな API 呼び出しが行われている？」「なぜ動かないの？」と言ったとき

手順

1. 問題のあるページに移動します：

   browser_navigate({ url: "..." })
   

2. 以下を並行して実行します（それぞれ独立しています）：

   browser_console_messages → JavaScript errors, warnings, logs
   browser_network_requests → API calls, failed requests, status codes
   

3. ページのスナップショットを取得します：

   browser_snapshot → current UI state, error messages, loading states
   

4. さらに調査します：

   browser_evaluate({ expression: "document.querySelectorAll('.error').length" }) → run custom JS
   

ワークフロー 4：複数ステップの移動

トリガー： ユーザーが「一連の流れを進めて」「サインアップのプロセスをテストして」「ウィザードを順に進めて」と言ったとき

手順

1. 開始ページに移動します：

   browser_navigate({ url: "..." })
   

2. 各ステップで：

   browser_snapshot → find the next action
   browser_click({ ref: "..." }) or browser_type({ ref: "...", text: "..." })
   browser_wait_for({ text: "expected content" }) → if page loads async
   

3. ダイアログが表示された場合は処理します：

   browser_handle_dialog({ accept: true }) → confirm/alert/prompt
   

4. 必要であれば戻ります：

   browser_navigate_back
   

ツールリファレンス

ナビゲーション

ツール	目的	パラメーター
browser_navigate	URL に移動	url（必須）
browser_navigate_back	戻る	なし
browser_wait_for	テキストまたは時間を指定して待機	text または timeout（ms）
browser_tabs	タブの一覧表示／切り替え	なし、または切り替え先の index

検査

ツール	目的	パラメーター
browser_snapshot	参照情報付きのアクセシビリティツリー	なし
browser_take_screenshot	画面のスクリーンショット	なし
browser_console_messages	JS コンソールの出力	なし
browser_network_requests	ネットワークアクティビティ	なし

操作

ツール	目的	パラメーター
browser_click	要素をクリック	ref（スナップショットから取得）
browser_type	テキストを入力	ref、text
browser_fill_form	複数のフィールドに入力	{ ref, value } の配列 fields
browser_select_option	ドロップダウンを選択	ref、values 配列
browser_hover	要素にカーソルを合わせる	ref
browser_drag	ドラッグ＆ドロップ	startRef、endRef
browser_press_key	キーボード入力	key（例："Enter"、"Tab"）
browser_file_upload	ファイルをアップロード	ref、paths 配列
browser_handle_dialog	ダイアログを確定／閉じる	accept のブール値

高度な機能

ツール	目的	パラメーター
browser_evaluate	JavaScript を実行	expression
browser_resize	ビューポートのサイズを変更	width、height
browser_close	ページを閉じる	なし
browser_install	ブラウザーをインストール	なし
browser_run_code	Playwright コードを実行	code 文字列

トラブルシューティング

「ブラウザーが実行されていません」または接続エラー

Playwright MCP サーバーは独自のブラウザーインスタンスを管理します。ツールが失敗する場合：

1. browser_install を実行して、ブラウザーのバイナリが利用可能であることを確認します
2. 簡単な URL に対して browser_navigate を実行します。これによりブラウザーが初期化される場合があります

ナビゲーション後に要素が見つからない

非同期コンテンツを含むページは、まだレンダリングされていない場合があります：

1. スナップショットを取得する前に、browser_wait_for({ text: "expected content" }) を使用します
2. 時間を指定して待機する場合は、browser_wait_for({ timeout: 2000 }) を使用します

プロキシ経由または内部ドメイン

MCP ブラウザーは、ネットワークトンネルを必要とするプロキシ経由または内部ドメインにアクセスできません。ローカル Supabase には http://127.0.0.1:54321 を直接使用します。

スナップショットの出力が非常に大きい

複雑なページでは、大きなアクセシビリティツリーが生成されます。出力が大きすぎる場合：

1. アプリ全体ではなく、特定のサブページに移動します
2. 代わりに browser_evaluate を使用して、特定の要素を検索します