Playwright MCPの導入から実践活用まで｜全主要エディタ対応の完全ガイド

AIコーディングエージェントが普及するなか、「ブラウザ操作だけは人の手が必要」という壁にぶつかるケースは多いです。Playwright MCPは、自然言語の指示だけでブラウザを自動制御できるMCPサーバーとして、この壁を取り除く存在になりつつあります。

本記事では、Playwright MCPの技術的な仕組みから、VS Code（GitHub Copilot）・Cursor・Claude Code・Claude Desktopそれぞれの設定手順、さらにE2Eテストやスクレイピングへの応用例まで、開発現場で即使える情報を体系的にまとめています。

Playwright MCPの概要と基本的な仕組み

Playwright MCPとは何か

Playwright MCPは、MicrosoftのPlaywrightチームが公式に開発・提供するMCP（Model Context Protocol）サーバーです。npmパッケージ名は @playwright/mcp で、Apache-2.0ライセンスのもとオープンソースとして公開されています。

GitHubリポジトリは2025年3月21日に作成され、最初のリリース（v0.0.7）は2025年3月28日に公開されました。2026年2月時点での最新バージョンはv0.0.64です（出典: GitHub Releases）。

従来のPlaywrightはTypeScriptやPythonのコードを書いてブラウザを操作するAPIライブラリですが、Playwright MCPはLLM（大規模言語モデル）やAIエージェントからの呼び出しに特化したサーバー実装です。両者は「関連はあるが根本的に異なるプロダクト」であり、Playwright MCPはPlaywrightの内部機能を活用しつつ、MCPプロトコルを通じてAIとブラウザを橋渡しします。

MCP（Model Context Protocol）の役割

MCPは2024年11月にAnthropicが提唱した通信規格で、AIアプリケーションと外部ツールを標準化された方法で接続します。Language Server Protocol（LSP）がエディタと言語サーバーの間を標準化したのと同様に、MCPはLLMと外部ツールの間を標準化するプロトコルです。

MCPの登場以前は、N個のAIアプリケーションとM個のツールを接続するには最大N×M個の個別コネクタが必要でした。MCPはこのN×M問題を解消し、MCP対応ツールであればどのMCP対応AIクライアントからも利用可能にします。2025年にはLinux Foundationに移管され、業界標準としての地位が固まりました。

アクセシビリティツリーによるページ表現

Playwright MCPの最大の技術的特徴は、ブラウザのページ情報をアクセシビリティツリーで表現する点です。

ブラウザ自動化技術は次のように変遷してきました。

世代	代表技術	ページの表現方法
第1世代	Selenium	DOMツリー＋CSSセレクタ
第2世代	Puppeteer / Playwright	DOM＋Chrome DevTools Protocol（CDP）
第3世代	Playwright MCP	アクセシビリティツリー（ARIA Snapshot）

従来のスクリーンショットベースのアプローチ（Vision Modelで画像解析する方式）と比較すると、アクセシビリティツリーには以下の利点があります。

トークン効率が高い: 画像データよりYAML形式のテキストのほうが遥かに軽量
構造を正確に把握できる: ボタンの意味やフォームの役割をセマンティックに伝達
安定性が高い: CSSの変更やレイアウト崩れに左右されにくい
高速に処理できる: Vision Modelへの問い合わせが不要

Playwright MCPが出力するARIA Snapshotの例は以下のとおりです。

- navigation "メインメニュー":
  - link "ホーム" [ref=e1]
  - link "製品" [ref=e2]
  - link "お問い合わせ" [ref=e3]
- main:
  - heading "製品一覧" [level=1]
  - list:
    - listitem:
      - link "製品A" [ref=e4]

LLMはこの構造化データを解釈し、refパラメータを使って操作対象の要素を指定します。スクリーンリーダーが「見る」ページ構造と同じ情報をAIが受け取る仕組みです。

Playwright MCPが提供するツール一覧

Playwright MCPはコアツール20個に加え、タブ管理とブラウザインストールの計22個のツールを標準で提供します。さらに --caps フラグを指定すると、座標ベース操作やPDF生成など追加12個（合計34個）が利用可能になります（出典: GitHub README）。

コアツール

カテゴリ	ツール名	機能概要
ナビゲーション	`browser_navigate`	指定URLへ遷移
ナビゲーション	`browser_go_back` / `browser_go_forward`	戻る・進む
ページ取得	`browser_snapshot`	ARIA Snapshotの取得（推奨）
ページ取得	`browser_take_screenshot`	PNGスクリーンショット保存
要素操作	`browser_click`	要素をクリック
要素操作	`browser_type`	テキストを入力（1文字ずつ）
要素操作	`browser_select_option`	セレクトボックスの選択
要素操作	`browser_hover`	ホバー
フォーム	`browser_fill_form`	フォームへの一括入力
キーボード	`browser_press_key`	特定キーの押下（Enter等）
スクリプト	`browser_evaluate`	任意のJavaScriptを実行
ネットワーク	`browser_network_requests`	ネットワークリクエストの取得
コンソール	`browser_console_messages`	コンソールログの取得
ファイル	`browser_file_upload`	ファイルアップロード
タブ	`browser_tab_list` / `browser_tab_new` / `browser_tab_select` / `browser_tab_close`	タブ管理
待機	`browser_wait_for`	条件を満たすまで待機
インストール	`browser_install`	Chromiumのセットアップ

–capsで有効化される追加ツール

--caps フラグでopt-inすると、以下の高度な機能が追加されます。

browser_pdf_save: ページをPDFとして保存
browser_mouse_move_xy / browser_mouse_click_xy: ピクセル座標ベースのマウス操作
browser_screen_capture: 画面全体のキャプチャ（Vision系ツール）
browser_generate_locator: テスト用ロケーターの生成
browser_verify_element_visible / browser_verify_text_visible / browser_verify_value / browser_verify_list_visible: テストアサーション

公式ドキュメントには browser_snapshot is preferred over screenshots for performing actions と明記されており、ARIA Snapshotがデフォルトの「ページを見る」手段として位置づけられています。

各エディタ・AIクライアントでの導入手順

動作要件

Node.js: バージョン18以上が必要
OS: Windows、macOS、Linuxに対応

Node.jsのバージョン確認は以下のコマンドで行います。

node --version
# v18.0.0 以上であればOK

VS Code + GitHub Copilotでの設定

VS Code v1.99以降が必要です。

手順1: エージェントモードを有効にします。VS Codeの設定（settings.json）を開き、以下を追加します。

{
  "chat.agent.enabled": true,
  "github.copilot.chat.agent.autoFix": true
}

手順2: MCPサーバーの設定を追加します。VS CodeのMCP設定ファイル（.vscode/mcp.json）を作成します。

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

手順3: VS Codeをリロードし、チャットパネルの入力欄を「Ask」から「Agent」に切り替えます。MCPサーバーが Running と表示されれば設定完了です。

Cursorでの設定

プロジェクトルートに .cursor/mcp.json を作成します。

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

Cursorの設定画面（Settings → MCP）でサーバーが認識されていることを確認してください。

Claude Codeでの設定

ターミナルで以下のコマンドを実行するだけで設定が完了します。

claude mcp add playwright npx @playwright/mcp@latest

設定後、Claude Code内で browser_navigate などのツールが利用可能になります。

Claude Desktopでの設定

Claude Desktopの設定ファイル（claude_desktop_config.json）に以下を追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

設定後、Claude Desktopを再起動すると利用可能になります。

3つのセットアップ構成の比較と選定基準

Playwright MCPの実行方法は大きく3種類あります。環境や用途に応じて最適な構成を選択します。

構成別の特性比較

特性	npx直接実行	Docker Compose常駐	Docker都度起動
Node.js	必須（v18+）	不要	不要
Docker	不要	必要	必要
初回セットアップ	約5分	約5分	約5分
起動速度	1〜2秒	1〜2秒（常駐時）	やや遅い
ストレージ消費	約300MB	約1GB	約1GB
メモリ消費	低（使用時のみ）	中〜高（常駐）	低（使用時のみ）
環境分離	なし	あり	あり
設定ファイル	`.mcp.json`のみ	`compose.yml` + `.mcp.json`	`.mcp.json`のみ

用途別の推奨構成

個人開発・チーム開発（ローカル環境）: npx直接実行がセットアップも簡単で最適
複数プロジェクトを横断して利用: Docker Compose常駐型で一元管理
CI/CDパイプライン・本番環境: Docker都度起動型でクリーンな環境を都度作成
DevContainer環境: npx直接実行がstdio接続との相性が良い

npx直接実行の設定例

プロジェクトルートに .mcp.json を配置します。

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

ヘッドレスモード（--headless）を指定すると、ブラウザのウィンドウを表示せずにバックグラウンドで動作します。CI環境やリモートサーバーでの利用時に指定してください。

Docker Compose常駐型の設定例

# compose.yml
services:
  playwright-mcp:
    image: mcr.microsoft.com/playwright:v1.52.0-noble
    working_dir: /app
    command: npx @playwright/mcp@latest --headless
    ports:
      - "3000:3000"
    volumes:
      - ./output:/app/output

// .mcp.json
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:3000"
    }
  }
}

E2Eテスト自動化への応用

Playwright MCPの代表的なユースケースがE2Eテストの自動生成です。

自然言語からテストシナリオを生成する流れ

AIにテスト対象のURLと確認したい操作を自然言語で伝える
Playwright MCPがブラウザを操作し、ARIA Snapshotでページ構造を取得
AIがページ構造を解釈し、操作手順を実行
実行結果をもとにPlaywrightのテストコードを自動生成

たとえばClaude Codeで以下のようにプロンプトを入力します。

https://example.com のログインフォームに
メールアドレス: test@example.com
パスワード: password123
を入力してログインボタンを押し、
ダッシュボード画面に遷移したことを確認してください。
その後、一連の操作をPlaywrightのテストコードとして出力してください。

AIはPlaywright MCPを通じてブラウザを実際に操作し、動作確認しながらテストコードを生成します。生成されたコードはそのままプロジェクトに組み込めます。

E2Eテスト自動化の実用的なポイント

向いているテストケース:

ログイン・ログアウトの基本フロー
フォーム入力とバリデーションの確認
画面遷移のシナリオテスト
レスポンシブデザインの目視確認（スクリーンショット比較）

注意が必要なケース:

複雑な待機条件を伴うテスト（ポーリング・WebSocket通信など）
大量のテストケースを並列実行するCI/CDパイプライン（従来のPlaywrightが適任）
ピクセル単位のビジュアルリグレッションテスト
外部サービス連携を伴うテスト（モック制御が困難な場合）

これらの場面では、従来のPlaywrightでテストコードを記述するほうが安定します。Playwright MCPは「探索的テストの高速化」と「テストコードの初期生成」に強みがあり、最終的に安定させたいテストは従来のPlaywrightコードへ移行するワークフローが実用的です。

スクレイピングと情報収集への応用

Playwright MCPはE2Eテスト以外にも、Webスクレイピングや情報収集の自動化に活用できます。

スクレイピングでの活用例

https://news.example.com を開いて、
トップニュース5件のタイトルとURLを取得して
JSON形式で出力してください。

AIは browser_navigate でページに遷移し、browser_snapshot でARIA Snapshotを取得した後、必要な情報を構造化して返します。JavaScriptで動的に描画されるSPA（Single Page Application）のコンテンツも、実際のブラウザで描画されるため取得可能です。

ログインが必要なサイトでの利用

認証が必要なサイトに対しては、--user-data-dir オプションでChromeプロファイルを永続化できます。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir", "./mcp-chrome-profile"
      ]
    }
  }
}

初回にログイン操作を実行すると、セッション情報（Cookie・ストレージ）がプロファイルディレクトリに保存され、次回以降はログイン状態が維持されます。

トラブルシューティング

プロファイルロックエラー

既にChromeが起動中の状態でPlaywright MCPを起動すると、プロファイルのロックエラーが発生する場合があります。対処法は以下のいずれかです。

起動中のChromeプロセスを終了する
--user-data-dir で別のプロファイルディレクトリを指定する
--headless モードで実行する

MCPサーバーが認識されない

設定ファイルの配置場所やJSON構文を確認してください。よくある原因は以下のとおりです。

.mcp.json がプロジェクトルートに配置されていない
JSON内にカンマの過不足がある
Node.jsのバージョンが18未満である

MCPサーバーの起動状態は、エディタのMCP設定画面で確認できます。VS Codeの場合はMCPパネルに Running と表示されていれば正常です。

Chromiumが起動しない（Linux / Docker環境）

Linux環境やDocker内では、必要な共有ライブラリが不足している場合があります。以下のコマンドで依存パッケージをインストールします。

npx playwright install --with-deps chromium

Docker環境では、公式のPlaywright MCPイメージ（mcr.microsoft.com/playwright/mcp）を使うとこの問題を回避できます。

ヘッドレスモードで画面が見えない

--headless を外すとブラウザウィンドウが表示されるため、動作確認時にはヘッドレスモードをオフにすることを推奨します。CI/CD環境のみ --headless を指定する運用が一般的です。

Playwright MCPと従来版Playwrightの棲み分け

Playwright MCPと従来のPlaywrightは排他的ではなく、補完的に利用するのが効果的です。

Playwright MCPが適している場面

探索的テスト: 自然言語で「このページを操作してみて」と試行錯誤できる
プロトタイプ作成: テストコードを書く前に動作を素早く確認
非エンジニアによるテスト: コーディングなしでブラウザ操作を自動化
RPA的な定型業務: データ入力や情報収集の自動化

従来のPlaywrightが適している場面

CI/CDパイプラインでの大規模テスト実行: 再現性と実行速度が重要
複雑な待機処理やリトライロジック: 細かな制御が必要
ビジュアルリグレッションテスト: ピクセル単位の比較
パフォーマンステスト: 実行時間の計測と最適化

実務ではPlaywright MCPで操作フローを探索し、安定したテストシナリオが確定したら従来のPlaywrightコードに落とし込むワークフローが有効です。Playwright MCPはテストコードの出力機能も備えているため、この移行は比較的スムーズに行えます。

まとめ

Playwright MCPは、AIエージェントとブラウザを自然言語で橋渡しする新しい自動化基盤です。

技術的な特徴: アクセシビリティツリー（ARIA Snapshot）によるページ表現が、トークン効率・安定性・セマンティック理解の面でスクリーンショットベースのアプローチを上回る
対応環境: VS Code（GitHub Copilot）・Cursor・Claude Code・Claude Desktopなど主要なAIコーディングツールに対応
導入の容易さ: npx一行で起動でき、Docker環境にも対応
実用的な活用先: E2Eテストの自動生成、スクレイピング、RPA的な定型業務の自動化

npmパッケージは @playwright/mcp で、ソースコードとドキュメントはGitHubリポジトリ（microsoft/playwright-mcp）で公開されています。

Playwright MCPの概要と基本的な仕組み#

Playwright MCPとは何か#

MCP（Model Context Protocol）の役割#

アクセシビリティツリーによるページ表現#

Playwright MCPが提供するツール一覧#

コアツール#

–capsで有効化される追加ツール#

各エディタ・AIクライアントでの導入手順#

動作要件#

VS Code + GitHub Copilotでの設定#

Cursorでの設定#

Claude Codeでの設定#

Claude Desktopでの設定#

3つのセットアップ構成の比較と選定基準#

構成別の特性比較#

用途別の推奨構成#

npx直接実行の設定例#

Docker Compose常駐型の設定例#

E2Eテスト自動化への応用#

自然言語からテストシナリオを生成する流れ#

E2Eテスト自動化の実用的なポイント#

スクレイピングと情報収集への応用#

スクレイピングでの活用例#

ログインが必要なサイトでの利用#

トラブルシューティング#

プロファイルロックエラー#

MCPサーバーが認識されない#

Chromiumが起動しない（Linux / Docker環境）#

ヘッドレスモードで画面が見えない#

Playwright MCPと従来版Playwrightの棲み分け#

Playwright MCPが適している場面#

従来のPlaywrightが適している場面#

まとめ#