Playwright MCP完全導入ガイド｜セットアップと実践

Q: Playwright MCP と Playwright Test の違いは？

MCP は **エージェント向けの対話的ブラウザ操作**。Test は **自動テストフレームワーク** です。目的が違います。

Q: スクリーンショットは使いますか？

主経路は accessibility snapshot ですが、スクリーンショットツールもあり **視覚確認** に使えます。

Q: Claude Code 以外でも使えますか？

はい。VS Code、Cursor、Claude Desktop、Windsurf、Cline 等、MCP 対応クライアントなら標準 config が使えます。

Q: --port 8931 は必須ですか？

必須ではありません。スタンドアロン HTTP モードを使うときの **公式例のポート** です。

Q: 日本語 UI のサイトも操作できますか？

スナップショットはアクセシビリティツリーに基づくため、日本語ラベルも通常は ref 経由で操作可能です。文字化けはスナップショット側より **フォント/CSS** 側の問題であることが多いです。

Q: Figma MCP と併用できますか？

可能です。デザイン取得は Figma MCP、実装確認は Playwright MCP、という役割分担が現実的です（[Figma MCP ガイド](/ja/blog/figma-mcp-jp)）。

Playwright MCP完全導入ガイド｜セットアップと実践

Playwright MCP とは

Playwright MCP は、Microsoft が提供する Model Context Protocol（MCP）サーバー で、LLM エージェントに ブラウザ操作能力 を付与します。ピクセルベースのスクリーンショット解析ではなく、ページの アクセシビリティツリー（accessibility snapshots） を構造化データとして返し、要素の ref（例: [ref=e5]）を使ってクリック・入力・ナビゲーションを行います。そのため ビジョンモデルが不要 で、VS Code、Cursor、Claude Code、Claude Desktop 等の MCP クライアントから安定して使えます。

正本は playwright-mcp GitHub リポジトリと Playwright MCP 公式ドキュメントです。本記事は 2026年7月時点の標準構成を軸に、セットアップから実践プロンプト、Docker・スタンドアロンサーバーまでを整理します。MCP 全般の概念は MCP 入門を先に読むと理解が早いです。

前提環境

項目	要件
Node.js	18 以上（Getting Started 明記）
MCP クライアント	VS Code、Cursor、Claude Code、Claude Desktop、Windsurf 等
OS	macOS / Windows / Linux（headed ブラウザ表示は GUI 環境が必要）
ネットワーク	`npx` で `@playwright/mcp@latest` を取得できること

初回起動時に Playwright ブラウザバイナリのダウンロードが走る場合があります。CI やオフライン環境では事前の npx playwright install 相当の準備を検討してください。

標準 MCP 設定（npx）

最も一般的な構成は npx @playwright/mcp@latest です。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

クライアントによって JSON のキー名（mcpServers / servers）や配置ファイル（mcp.json / Claude Code の MCP レジストリ）が異なりますが、command + args の実体は上記が公式の標準形です。

Claude Code への追加

Claude Code では次の1行が公式クイックスタートです。

claude mcp add playwright npx @playwright/mcp@latest

追加後、/mcp で接続状態を確認し、エージェントにブラウザ操作を依頼します。例（First interaction より）:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

エージェントは Playwright MCP のツールでページを開き、スナップショット上の ref を使って todo を追加します。

VS Code への追加

UI / CLI

公式は VS Code 用インストールボタンに加え、CLI 例として次を示しています。

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

mcp.json を手動編集する場合も、上記 command / args と同等のエントリを servers に追加します。

Cursor への追加

Cursor では Settings → MCP → Add new MCP Server から command タイプ で npx @playwright/mcp@latest を指定する手順が Getting Started に記載されています。Cursor Agent から「ローカル http://localhost:3000 を開いてコンソールエラーを確認して」と依頼するユースケースと相性が良いです（Cursor 入門と併読可）。

accessibility snapshots の読み方

Playwright MCP が返すスナップショットは、おおよそ次のようなテキスト構造です。

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

LLM は ref=e5 に入力、ref=e10 をクリック といった指示で DOM を操作します。CSS セレクタを毎回推測するより ロールと名前 が明示されるため、動的 UI でも再現性が上がりやすい、というのが公式が強調する設計です。

主要ツールカテゴリ（概要）

公式ドキュメントが列挙する能力（詳細なツール名は GitHub 正本を参照）:

カテゴリ	できること
Navigation	URL オープン、戻る/進む、リロード
Click / Type	クリック、入力、フォーム、セレクト
Screenshot	ページまたは要素のキャプチャ（視覚確認用）
Keyboard / Mouse	キー、ホバー、ドラッグ＆ドロップ
Dialogs	alert/confirm の accept/dismiss
Tabs	タブ作成・切替・クローズ
Network	リクエスト一覧、ルート mock、コンソールログ
Storage	cookie / localStorage の保存・復元

browser_run_code_unsafe

複雑な操作は browser_run_code_unsafe で Playwright スクリプトを直接実行できます。公式は RCE 相当 と明記しており、信頼できる MCP クライアントにだけ有効化 すべきです。

Run this Playwright code to verify the todo count:
async (page) => {
  const count = await page.getByTestId('todo-count').textContent();
  return count;
}

設定オプション

Headed / Headless

既定は headed（ブラウザ UI が見える）。ヘッドレス化:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    }
  }
}

ブラウザ選択

"args": ["@playwright/mcp@latest", "--browser=firefox"]

サポート: chrome, firefox, webkit, msedge（Configuration）。

プロファイルモード

Persistent（既定）: ログイン状態をセッション間で保持
Isolated: --isolated で毎回クリーン
Browser extension: --extension で既存ブラウザタブに接続

設定ファイル

npx @playwright/mcp@latest --config path/to/config.json

高度な timeout、network ルール等は GitHub リポジトリの schema を参照してください。

スタンドアロンサーバー（--port 8931）

ディスプレイのない環境や IDE の worker プロセスから headed ブラウザを扱う場合、HTTP トランスポートで別プロセス起動 が有効です。

npx @playwright/mcp@latest --port 8931

クライアント側は URL 指定:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

ポート 8931 は公式 Quick Reference の例です。ファイアウォールや他サービスとの競合時は変更可能ですが、クライアントとサーバーで一致させてください。

Docker（mcr.microsoft.com/playwright/mcp）

コンテナで MCP サーバーを動かす場合、Microsoft の Playwright MCP 用イメージ mcr.microsoft.com/playwright/mcp が GitHub / docs で案内されています。GUI 表示が必要な headed モードでは X11 転送や VNC 等の追加設定が必要になることが多く、ローカル開発では npx 直起動の方がトラブルが少ないケースもあります。本番 CI 向けのヘッドレス検証では Docker + --headless の組み合わせを検討してください。

実践プロンプト例

目的	プロンプト例
スモークテスト	`http://localhost:3000/ja を開き、ヒーロー見出しが表示されるか確認して`
フォーム	`デモサイトのログインフォームに test@example.com を入力して送信ボタンを押して`
回帰確認	`前回保存した storage state を使ってダッシュボードまで遷移できるか確認して`

API レスポンスのモック（browser_route 等）は、公式 README では network capability の opt-in が必要な場合があります。使うときは args に例えば --caps=network を足すなど、playwright-mcp README の capability 節を確認してください。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--caps=network"]
    }
  }
}

E2E テストコード生成そのものより、エージェントが対話的にページを触る 用途で Playwright MCP の価値が出やすいです。テストスイート化する段階では通常の @playwright/test プロジェクトへ移行するのが一般的です。

セキュリティと運用上の注意

browser_run_code_unsafe は任意コード実行。本番 DB や管理画面への無制限アクセスと組み合わせない
エージェントに 本番 URL と 本番認証情報 を渡す場合は read-only 環境を推奨
MCP ツール呼び出しはトークンと時間を消費する。長大なページではスナップショットサイズに注意
複数 MCP（Figma、Serena 等）併用時は、エージェントが どのツールを使うか プロンプトで明示すると成功率が上がる

よくあるつまずき

症状	原因	対処
MCP が起動しない	Node < 18	`node -v` で確認、アップグレード
ブラウザが開かない	ヘッドレス/ディスプレイ不足	headed 設定、または `--port` 分離
npx が毎回遅い	都度ダウンロード	グローバル pin や config ファイルで固定
ref が見つからない	UI 変更・タイミング	リロード指示、待機をプロンプトに含める
Claude が Playwright を使わない	ツール未接続	`/mcp` で playwright サーバー状態確認

FAQ

Q. Playwright MCP と Playwright Test の違いは？ MCP は エージェント向けの対話的ブラウザ操作。Test は 自動テストフレームワーク です。目的が違います。

Q. スクリーンショットは使いますか？ 主経路は accessibility snapshot ですが、スクリーンショットツールもあり 視覚確認 に使えます。

Q. Claude Code 以外でも使えますか？ はい。VS Code、Cursor、Claude Desktop、Windsurf、Cline 等、MCP 対応クライアントなら標準 config が使えます。

Q. --port 8931 は必須ですか？ 必須ではありません。スタンドアロン HTTP モードを使うときの 公式例のポート です。

Q. 日本語 UI のサイトも操作できますか？ スナップショットはアクセシビリティツリーに基づくため、日本語ラベルも通常は ref 経由で操作可能です。文字化けはスナップショット側より フォント/CSS 側の問題であることが多いです。

Q. Figma MCP と併用できますか？ 可能です。デザイン取得は Figma MCP、実装確認は Playwright MCP、という役割分担が現実的です（Figma MCP ガイド）。

設定の正本: github.com/microsoft/playwright-mcp / playwright.dev/docs/getting-started-mcp

LINE登録で Claude Code 特典キットを受け取る

スライド自動作成キット・スターターキットを無料プレゼント。友だち登録するだけで受け取れます。

LINEで受け取る →

最終確認日: 2026-07-23

Playwright MCP完全導入ガイド｜セットアップと実践

Playwright MCP完全導入ガイド｜セットアップと実践

Playwright MCP とは

前提環境

標準 MCP 設定（npx）

Claude Code への追加

VS Code への追加

UI / CLI

Cursor への追加

accessibility snapshots の読み方

主要ツールカテゴリ（概要）

browser_run_code_unsafe

設定オプション

Headed / Headless

ブラウザ選択

プロファイルモード

設定ファイル

スタンドアロンサーバー（--port 8931）

Docker（mcr.microsoft.com/playwright/mcp）

実践プロンプト例

セキュリティと運用上の注意

よくあるつまずき

FAQ

関連記事

関連サービス

LINE登録で Claude Code 特典キットを受け取る

関連記事