Playwright MCP完全ガイド2026｜AIブラウザ自動化の仕組みと実装

「AIエージェントにブラウザを操作させたいが、Computer Useのトークン代が高すぎる…」

こういう悩みを持つ開発者がここ数ヶ月で急増している。スクリーンショットをLLMに送ってピクセル座標で操作させるVision型アプローチは確かに汎用性が高いが、1タスクで数万トークンを消費するのは財布に厳しい。それに、Webページのボタンをクリックするだけなのに視覚モデルを使うのは明らかにオーバースペックだ。

そこで注目されているのがPlaywright MCPだ。MicrosoftがPlaywrightをMCPサーバーとして実装したもので、2026年6月時点でGitHubスター数3.4万を超え、65種類以上のブラウザ操作ツールを提供している。この記事では、仕組みから始めてセットアップ・主要ツールの使い分け・実装例・Vision型との判断フローまでを一気通貫で解説する。

Playwright MCPの仕組み｜アクセシビリティツリーとは何か

まず「なぜ視覚モデルが不要なのか」を理解しておこう。従来のVision型ブラウザ自動化（Anthropic Computer Use、browser-useのスクリーンショットモード等）は、ページをスクリーンショットとして撮影してLLMに渡し、「ボタンはここにある」をピクセル座標で判断させる。この方式の問題点は2つある。

1. トークンコストが高い：1枚のスクリーンショットを処理するだけでVision系モデルは1万〜5万トークンを消費する。複数ステップの自動化では積み重なってかなりの費用になる。
2. 非決定論的：「ボタンっぽいもの」を座標で探すため、デザイン変更やレイアウト崩れで即座に壊れる。

Playwright MCPはまったく異なるアプローチを取る。ページを「アクセシビリティツリー」と呼ばれる構造化されたテキストデータとしてLLMに渡す。アクセシビリティツリーとはスクリーンリーダー（視覚障害者向け補助ツール）が使うのと同じ情報で、「ここにbuttonという役割の要素があり、テキストは”送信”で、参照IDはe47」といったデータが含まれる。

スナップショットの実例

実際にPlaywright MCPがLLMに渡すスナップショットはこのようなテキストになる：

- button "送信" [ref=e47]
- textbox "メールアドレス" [ref=e12] value=""
- link "パスワードを忘れた場合" [ref=e55] url="https://example.com/reset"

このデータは200〜400トークン程度だ。同じページのスクリーンショットが1万トークン以上かかるのと比べると、いかにコンパクトかがわかる。そしてLLMは ref=e47 のIDを使って「このボタンをクリックして」という命令を出す。これが「決定論的」と言われる理由で、ピクセル座標ではなくセマンティックIDで操作するため、デザイン変更に強い。

スナップショット型 vs Vision型 比較表

セットアップ｜Claude Code・Claude Desktop・Cursorへの接続

セットアップは拍子抜けするほど簡単だ。まずnpxが使える環境（Node.js 18以上）を前提に進める。

Claude Codeへの追加（推奨・最速）

Claude Codeを使っているなら1コマンドで完了する。

# グローバルに追加
claude mcp add playwright npx @playwright/mcp@latest

# プロジェクト固有に追加（.mcp.json）
claude mcp add playwright npx @playwright/mcp@latest --scope project

追加後は claude mcp list で確認できる。次にClaude Codeを再起動するとPlaywrightツールが使えるようになる。

Claude Desktopへの追加

設定ファイルを直接編集する。macOSの場合は ~/Library/Application Support/Claude/claude_desktop_config.json を開いて以下を追記する。

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

Windowsの場合は %APPDATA%Claudeclaude_desktop_config.json が対象だ。設定後にClaude Desktopを再起動する。

CursorとVS Codeへの追加

# Cursor: 設定 → MCP → 新規サーバー追加で以下を入力
npx @playwright/mcp@latest

# VS Code: コマンドラインから
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

Headless／Headedモードの切り替え

デフォルトではブラウザウィンドウが表示されるheadedモードで動作する。CI環境や自動化スクリプトではheadlessが便利だ。

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

逆に、--headlessを外してウィンドウを表示させながら動作を確認したいデバッグ時にはそのままデフォルト設定を使えばよい。

主要ツール一覧｜65種類の使い分け方

Playwright MCPは執筆時点（2026年6月）で65種類以上のツールを提供している。全部を覚える必要はなく、実務でよく使う「コアツール10選」を押さえておけばほとんどのユースケースをカバーできる。

コアツール10選

オプトインで追加できる高度ツール

以下のツールはデフォルトでは無効で、設定ファイルに --caps オプションを追加することで有効化できる。

実装例3選｜フォーム入力・スクレイピング・E2Eテスト

実装例1：ログインフォームの自動入力

Claude Codeのチャットで以下のように指示するだけで動作する：

# Claude Codeでのプロンプト例（日本語でOK）
https://example.com/login にアクセスして、
メールアドレス欄に "test@example.com"、
パスワード欄に "password123" を入力し、
ログインボタンをクリックしてください。

裏側では以下のようなツール呼び出しが行われる（Claude Codeの内部動作）：

# 1. ページを開く
browser_navigate(url="https://example.com/login")

# 2. アクセシビリティツリーを取得してフォーム要素のrefを確認
browser_snapshot()
# 返り値例: textbox "メールアドレス" [ref=e12], textbox "パスワード" [ref=e15], button "ログイン" [ref=e20]

# 3. メールアドレスを入力
browser_fill(ref="e12", value="test@example.com")

# 4. パスワードを入力
browser_fill(ref="e15", value="password123")

# 5. ログインボタンをクリック
browser_click(ref="e20")

本番環境で使用する前に、必ずテスト環境で動作確認してください。特に認証情報を含む自動化処理は、APIキーや個人情報を環境変数で管理し、ハードコードしないこと。

実装例2：Eコマースサイトのスクレイピング

商品一覧ページから価格と商品名を抽出する例だ。アクセシビリティツリーを使うため、JavaScriptが動的に生成したコンテンツも問題なく取得できる。

# Claude Codeへの指示
https://shop.example.com/products の商品一覧ページを開いて、
表示されているすべての商品名と価格をリストにして返してください。

# Playwright MCPが内部で実行する処理
browser_navigate(url="https://shop.example.com/products")
browser_snapshot()
# → heading "商品A" [ref=e5], text "¥1,980" [ref=e6] のような構造化データを返す
# → LLMがrefを参照しながら情報を抽出してMarkdownリスト形式に変換

従来のスクレイピングツール（Beautiful Soup等）との違いは、XPathやCSSセレクタをゼロコードで書けるという点だ。LLMがアクセシビリティツリーを見て「どの要素が商品名でどれが価格か」を意味的に判断する。

実装例3：フォーム送信のE2Eテスト自動化

以下はMCP設定ファイルを使ったよりシステマティックなE2Eテスト構成の例だ。

// playwright-mcp-config.json
{
  "browser": {
    "browserName": "chromium",
    "headless": true,
    "viewport": { "width": 1280, "height": 720 }
  },
  "contextOptions": {
    "locale": "ja-JP",
    "timezoneId": "Asia/Tokyo"
  },
  "timeout": 30000
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--config",
        "./playwright-mcp-config.json"
      ]
    }
  }
}

この設定を使うことで、日本語ロケール・タイムゾーン固定の環境で再現性の高いテストを実行できる。CI/CDパイプラインで使う場合は "headless": true が必須だ。

Vision Modeが必要なケース｜スナップショットで対応できない例

Playwright MCPのスナップショットモードが万能ではない点も理解しておく必要がある。アクセシビリティツリーを持たないUI要素は、スナップショットモードでは操作できない。

Vision Modeが必要なユースケース

Vision ModeへのアップグレードJSON設定

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

Vision Modeを有効化すると browser_mouse_click_xy（座標クリック）や browser_mouse_drag_xy（ドラッグ）などのツールが追加される。ただしこれらはスクリーンショットを必要とするため、トークン消費量が増える点に注意が必要だ。

ブラウザ自動化ツール選定フロー

どのツールを選ぶか迷ったときの判断フローを以下にまとめた。

よくある失敗パターンと回避策

失敗1：browser_snapshotを使わずに操作しようとする

❌ よくある間違い：browser_navigateでページを開いた直後に、スナップショットを取らずに browser_click(ref="e47") を実行しようとする。

⭕ 正しいアプローチ：操作前に必ず browser_snapshot() を呼んで現在のrefを確認する。refの値はページ遷移やDOMの更新で変わるため、毎回取得が基本だ。

失敗2：headlessでCookieが引き継がれない

❌ よくある間違い：headlessモードでログインが必要なサイトを操作しようとしてセッションが切れる。

⭕ 正しいアプローチ：設定ファイルの contextOptions に storageState を指定してCookieを永続化するか、--storage-state オプションを使う。

// セッション保存付きの設定例
{
  "browser": { "headless": true },
  "contextOptions": {
    "storageState": "./auth-state.json"
  }
}

失敗3：Vision Modeのトークン爆発

❌ よくある間違い：--caps=vision を有効にしたまま標準的なWebページの操作に使い続ける。スクリーンショットが毎回送られてトークンコストが急増する。

⭕ 正しいアプローチ：Vision Modeは本当に座標操作が必要な場合のみ有効化する。標準Webページはスナップショットモードで十分だ。

失敗4：アクセシビリティが実装されていないサイトでの誤判定

❌ よくある間違い：aria属性がまったく設定されていないレガシーサイトに対してスナップショットモードで操作を試みる。スナップショットが空に近い状態になり、LLMが操作対象を見つけられない。

⭕ 正しいアプローチ：browser_snapshot() の返り値を確認し、有意義な要素がなければVision Modeに切り替えるか、browser_evaluate でJavaScript直接実行を検討する。

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

公式ドキュメントが明記しているとおり、「Playwright MCPはセキュリティバウンダリではない」。つまり、AIエージェントがPlaywright MCPを使ってブラウザを操作できる状態は、そのエージェントに物理的なブラウザへのフルアクセスを与えているのと同義だ。

• ネットワーク制限：設定ファイルの allowedOrigins と blockedOrigins で操作対象ドメインを制限する。本番環境の管理画面やデータベースUIへの接続は必ず制限すること。
• Dockerコンテナ化：MicrosoftはHeadless専用ChromiumをDockerで動かす構成を公式に提供している。外部公開するAPIとしてPlaywright MCPを使う場合は必ずDockerで隔離する。
• MCP Tool Poisoning対策：悪意あるWebページがアクセシビリティツリーに隠しインストラクションを埋め込むリスクがある。詳細はMCP Tool Poisoning防御ガイドを参照してほしい。
• 認証情報はシークレット管理を使う：Playwright MCPの設定ファイルにAPIキーやパスワードをハードコードしない。環境変数（.env）かシークレットマネージャー経由で渡すこと。

まとめ：今日から始める3つのアクション

1. 今日やること：claude mcp add playwright npx @playwright/mcp@latest を実行し、任意のWebページで browser_navigate → browser_snapshot を試して動作確認する（5分で完了）。
2. 今週中：実業務で繰り返しているWebフォーム入力・レポートDL・定点スクレイピングのうち1つをPlaywright MCPで自動化する。
3. 今月中：E2Eテストスイートに組み込み、CIパイプライン（headlessモード）での継続実行体制を整える。

あわせて読みたい：

• Browser-use完全ガイド2026｜AIエージェントのブラウザ自動化 — Python nestedエージェントとの比較に
• Stagehand完全ガイド2026｜TypeScriptブラウザエージェント — TypeScript派はこちら
• MCP Tool Poisoning防御2026 — セキュリティを固める前に必読
• Computer Use APIをPython+Dockerで動かす実装ガイド — Vision型が必要な場合の実装例

参考・出典

• Playwright MCP Getting Started — Microsoft/Playwright公式（参照日: 2026-06-12）
• Vision Mode — Playwright MCP — Microsoft/Playwright公式（参照日: 2026-06-12）
• microsoft/playwright-mcp — GitHub — スター数・ツール一覧・バージョン情報（参照日: 2026-06-12）
• Playwright MCP: All 23 Core Tools and mcp.json Configs — MorphLLM — ツール設定詳細（参照日: 2026-06-12）
• Playwright MCP Explained: Setup, Config & Real-World Examples — TestDino — セットアップ手順（参照日: 2026-06-12）

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人以上。著書『AIエージェント仕事術』。
AIエージェント導入・研修・開発支援。
ご質問・ご相談は お問い合わせフォーム からどうぞ。