Playwright MCP 実践ガイド：Claude、Codex、Cursor からブラウザを直接操作する

.codex/config.toml に [mcp_servers.playwright] を 1 行足し、codex を起動するとブラウザは確かに開きます。それでも AI がブラウザツールを呼ばない、あるいはページは開いたのにナビゲーションバーのボタンを見つけられない。この記事では、Claude Code、Codex、Cursor の 3 つの client での設定手順、最初の検証タスクの受け入れチェックリスト、そして AI に気軽に渡してはいけないブラウザ権限を整理します。

---

Playwright MCP とは

Playwright MCP は Microsoft が公式に保守する MCP server です。Playwright のブラウザ自動化機能を Model Context Protocol 経由で AI コーディングツールに公開します。中心にあるのはスクリーンショット認識ではなく、accessibility tree の操作です。AI にページの構造化ビューを渡し、ボタン、リンク、入力欄などの操作可能な要素を見つけられるようにします。

主な機能とツール一覧

Playwright MCP が提供するツールは、ブラウザ自動化の主要な場面をカバーします。

• ナビゲーション：URL を開く、戻る、進む、更新する
• クリックと入力：要素をクリックする、フォームへ入力する、キーボード操作を行う
• スクリーンショットと snapshot：ページのスクリーンショットを撮る、accessibility snapshot を取得する
• ダイアログとタブ：alert/confirm/prompt を処理する、複数タブを管理する
• ネットワークと console：ネットワークリクエストを確認する、console log を取得する
• 保存状態：cookies、localStorage、sessionStorage を保存・復元する

これらの機能により、単純なページクリックから複雑なフォーム送信まで扱えます。

Playwright CLI/SKILLS との違い

Microsoft の公式 README は、2 つのルートの取捨選択を明確に示しています。

• MCP ルート：永続状態、豊富な introspection、継続的なブラウザコンテキストが必要な場面に向きます。探索的自動化、自動修復テスト、長時間タスクなどです。一方で tool schema と accessibility tree がコンテキストに入り、token を消費します。
• CLI + SKILLS ルート：高スループットのコード作業に向きます。コンテキスト消費は小さくなりますが、Playwright をコマンドラインやスクリプトから呼び出す必要があります。

Claude Code、Codex、Cursor のような MCP 対応 AI コーディングツールをすでに使っているなら、Playwright MCP は既存の作業環境へブラウザツールを入れる最短ルートです。

Browser Use との違い

Browser Use は Python の agent loop です。Python コードで API を呼び出し、agent が prompt に応じてブラウザ操作を決めます。Playwright MCP は違います。agent loop は提供せず、ブラウザツール層だけを提供します。いつブラウザツールを呼ぶかは、Claude Code、Codex、Cursor など既存の MCP client が判断します。

Python 開発者として Browser Agent をすばやく試したいなら、AI でページを開き、ボタンをクリックし、情報を抽出する Browser Use 入門を先に読むとよいでしょう。すでに MCP client を使っていて、既存ツールにブラウザ機能を接続したいなら、この記事で Playwright MCP のインストール、疎通確認、安全設定まで進められます。

テストフレームワークの代替ではない

Playwright MCP は Playwright テストフレームワークの代替ではありません。探索的自動化やフロントエンド検収には向いていますが、安定した E2E テストスイートは Playwright テストフレームワーク でテストスクリプトを書く必要があります。テストには決定性、再現性、保守性が必要で、AI のブラウザ操作は完全には制御できないからです。ブラウザモードでのテストに興味があるなら、Vitest Browser Mode も参考になります。

---

Claude Code で Playwright MCP を設定する

前提条件

Claude Code で Playwright MCP を動かすには Node.js 18+ が必要です。Node のバージョンを確認します。

node --version

18 未満であれば、先に Node.js をアップグレードします。

追加コマンド

Claude Code には MCP 管理用のコマンドがあります。プロジェクトルートで実行します。

claude mcp add playwright npx @playwright/mcp@latest

このコマンドで Playwright MCP server が Claude Code に登録されます。@playwright/mcp@latest を使ってください。@executeautomation/playwright-mcp-server のような古いコミュニティパッケージ名をコピーしないようにします。

プロジェクトレベルの .mcp.json

Playwright MCP の設定をチームメンバーと共有したい場合は、プロジェクトルートに .mcp.json を作成できます。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/usr/bin/chromium"
      }
    }
  }
}

Claude Code はプロジェクトレベルの .mcp.json を見つけると承認を求めます。プロジェクトが信頼していない MCP server を持ち込むことを防ぐためです。

環境変数の展開

.mcp.json は、マシンごとのパスや機密値のために環境変数展開をサポートします。

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

Tool Search と出力 token 管理

Claude Code はデフォルトで MCP Tool Search を有効にします。ツールを遅延読み込みし、コンテキスト消費を抑えるためです。MCP の出力が大きい場合、Claude Code は token 管理も行い、デフォルトの最大出力は 25,000 tokens です。AI がブラウザツールを使わない場合は、次を確認します。

1. MCP server が正しく起動しているか（Claude Code のログを見る）
2. Tool Search が有効か（Claude Code ではデフォルトで有効）
3. Node.js のバージョンが 18 以上か

---

Codex で Playwright MCP を設定する

OpenAI Codex は CLI と IDE extension の両方で MCP servers をサポートします。ただし設定方法は Claude Code と異なります。

追加コマンド

Codex CLI には MCP 管理コマンドがあります。

codex mcp add playwright -- npx @playwright/mcp@latest

Codex では server 名と実際のコマンドを -- で分ける点に注意します。

設定ファイルの場所

Codex MCP の設定は config.toml に保存されます。場所は 2 つあります。

• ユーザーレベル：~/.codex/config.toml（全体に適用）
• プロジェクトレベル：プロジェクトルートの .codex/config.toml（そのプロジェクトだけに適用）

CLI と IDE extension は同じ設定を共有します。

config.toml の設定片

手動で設定する場合は、config.toml に次を追加します。

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

環境変数の受け渡しやツール承認を調整したい場合は、さらに追加します。

env_vars = ["HOME", "STORAGE_STATE_PATH"]
approval_mode = "prompt"

ツール承認モード

Codex には 3 つのツール承認モードがあります。

• approval_mode = "allow"：すべてのツール呼び出しを自動実行する
• approval_mode = "prompt"：各ツール呼び出しの前にユーザー確認を求める
• approval_mode = "deny"：すべてのツール呼び出しを拒否する

Playwright MCP の高リスクツール（例：browser_run_code_unsafe）には、次のような設定をおすすめします。

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_run_code_unsafe"]
approval_mode = "prompt"

これにより高リスクツールの自動実行を防ぎ、機密操作を人間の承認の後ろに置けます。

HTTP server のサポート

Codex は 2 種類の MCP server をサポートします。

• STDIO server：ローカルプロセス通信です。Playwright MCP のようにローカルシステムへアクセスするツールに向いています
• HTTP server：bearer token と OAuth 認証をサポートします

Playwright MCP は STDIO を使うため、通常は HTTP 設定は不要です。

---

Cursor で Playwright MCP を設定する

Cursor の MCP 設定は Settings UI から行います。Claude Code や Codex のコマンドライン方式とは違います。

UI 設定手順

Playwright 公式ドキュメントによると、Cursor の設定手順は次のとおりです。

1. Cursor Settings を開く（Cmd+, またはメニューバーの Settings）
2. MCP 設定ページへ移動する（Settings -> MCP）
3. 「Add new MCP Server」をクリックする
4. 設定を入力する：
   • Server name：playwright
   • Command type：npx
   • Command：@playwright/mcp@latest

標準パラメータ設定

Cursor の MCP server 設定では、Playwright MCP の標準パラメータを使えます。

• --headless：ヘッドレスモード。開発段階では headed のほうが観察しやすいです
• --browser：ブラウザを選ぶ（chrome/firefox/webkit/msedge）
• --output-dir：出力ディレクトリのパス
• --storage-state：ログイン状態ファイルのパス

詳しいパラメータは、後述の「標準設定パラメータ対照表」を参照してください。

設定リファレンス

Cursor 公式 MCP ドキュメントは Cursor 公式ドキュメント から確認できます。設定の詳細は Playwright 公式ドキュメントと Microsoft README を基準にし、公式パッケージ名 @playwright/mcp@latest を使ってください。

---

標準設定パラメータ対照表

Playwright MCP には、ブラウザ挙動、安全境界、出力管理を制御する複数の設定パラメータがあります。

パラメータ	役割	デフォルト	安全上の注意
--headless	ブラウザウィンドウを表示しないヘッドレスモード	false（headed）	開発段階ではブラウザ操作を観察しやすい headed がおすすめ
--browser	ブラウザ種別を選ぶ	chrome	chrome、firefox、webkit、msedge を選択可能
--allowed-origins	許可する origin の一覧	制限なし	安全境界ではありません。redirects に影響せず、機密サイトへのアクセス防止には使えません
--blocked-origins	ブロックする origin の一覧	なし	安全境界ではありません。上と同じ注意が必要です
--isolated	隔離モード。セッションごとに独立 profile を使う	false	並行 client や複数プロジェクトで推奨
--storage-state	ログイン状態ファイルのパスを指定する	なし	cookies と localStorage を保存します。実アカウントでは慎重に使います
--output-dir	スクリーンショットやログなどの出力先	なし	結果を探しやすいようにパスを指定します
--save-session	セッション状態を保存する	false	persistent profile と組み合わせて使います
--snapshot-mode	accessibility snapshot のモード	default	snapshot の詳細度を制御します
--allow-unrestricted-file-access	制限なしのファイルアクセスを許可する	false	高リスクです。慎重に有効化してください
--secrets	環境変数またはファイルによる secret 設定	なし	機密情報管理に使います

重要な注意：公式は --allowed-origins と --blocked-origins が 安全境界ではなく、redirects にも影響しないと明記しています。AI がアクセスできるサイトを制限したい場合、この 2 つのパラメータだけに依存してはいけません。

---

Profile モード 3 ルート対照表

Playwright MCP は 3 つの profile モードをサポートし、ログイン状態の保存、並行実行、安全境界に影響します。

モード	ログイン状態の保存	Profile パス	並行実行	向いている場面	安全上のおすすめ
persistent	cookies、localStorage などを保存	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	1 つの profile は同時に 1 つの browser instance だけが使用可能	AI にログイン状態を覚えさせたい長時間タスク	実アカウントは避け、テストアカウントから始める
isolated	保存しない。各セッションが独立	一時ディレクトリ。セッションごとに自動削除	並行 client や複数プロジェクトに対応	テスト、探索、ログイン状態が不要な場面	本番環境の第一候補として推奨
browser extension	保存する（ブラウザに依存）	ブラウザ拡張ディレクトリ	ブラウザに依存	既存のブラウザセッションへ接続する	高度な使い方。ブラウザ拡張のセキュリティモデルを理解してから使う

persistent profile の制限

1 つの persistent profile は、同時に 1 つの browser instance だけが使えます。複数 client や複数プロジェクトで同時に Playwright MCP を使う場合は、次のどちらかが必要です。

• --isolated モードを使う
• または client ごとに別々の --user-data-dir を設定する

macOS での persistent profile パス例です。

~/Library/Caches/ms-playwright/mcp-chrome-a1b2c3d4

パス内の {workspace-hash} はプロジェクトに応じて自動生成され、プロジェクトごとに別の profile が使われます。

ログイン状態と安全境界

persistent profile は cookies、localStorage、sessionStorage を保存します。AI はブラウザ内に保存されたログイン状態へアクセスできます。実アカウントでログインしていると、個人データ、決済情報、アカウント設定へアクセスできる可能性があります。

おすすめの運用：

• 本番環境では --isolated を使い、ログイン状態を保存しない
• AI にログイン状態を扱わせる必要がある場合は、実アカウントではなくテストアカウントを使う
• AI に実アカウントへ自動ログインさせたり、決済ページへアクセスさせたりしない

ログイン状態管理の詳細は、後続の「AI ブラウザログイン状態管理」で扱います。この記事では境界だけを押さえます。

---

browser_run_code_unsafe の安全警告

安全警告：browser_run_code_unsafe は任意の Playwright スクリプトを実行できます。公式は RCE-equivalent（リモートコード実行相当）と明記しています。完全に信頼できる MCP clients でのみ有効化し、本番環境では無効化するか Codex の approval_mode: prompt で人間の承認を必須にします。

Playwright MCP には browser_run_code_unsafe という高リスクツールがあります。これはブラウザコンテキストで任意の Playwright スクリプトを実行できます。危険な理由は明確です。

• MCP client が侵害されたり AI の挙動を制御できなかったりすると、攻撃者がこのツール経由で任意コードを実行できます
• AI は cookies、localStorage、sessionStorage、ログイン済みアカウントの個人情報を含む、ブラウザ内のすべてのデータを読めます
• ブラウザが決済ページやアカウント設定ページを開いている場合、AI が機密データを読み取り外部へ漏らす可能性があります

安全設定のおすすめ

本番環境：

1. browser_run_code_unsafe を無効化します。

   Codex の ~/.codex/config.toml に追加します。

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   disabled_tools = ["browser_run_code_unsafe"]

2. または承認モードを設定します。

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   approval_mode = "prompt"

   これにより browser_run_code_unsafe の呼び出し前に Codex が確認ダイアログを出し、手動承認が必要になります。

開発環境：

どうしても browser_run_code_unsafe を使う必要がある場合は、次を守ります。

• ローカル開発環境だけで有効化し、本番環境や実アカウントでは使わない
• 実行するスクリプト内容を完全に理解していることを確認する
• AI にスクリプトを自動生成させてそのまま実行させず、自分で書いた既知のスクリプトを AI に実行させる

初心者にはおすすめしない

Playwright MCP を触り始めたばかりなら、browser_run_code_unsafe は使わないほうがよいです。まずは browser_click、browser_navigate、browser_screenshot など、Playwright MCP が提供するより安全なツールを使います。これらは境界が明確で、任意コードを実行しません。

---

MCP Tools の安全チェックリスト

MCP により AI は外部ツールを呼び出せます。ただし「MCP を接続した」ことは「AI に何でも自動実行させる」ことではありません。client 側と server 側の両方で安全境界を制御する必要があります。

client 側の安全おすすめ

1. 機密操作ではユーザー確認を求める：browser_run_code_unsafe の呼び出し、決済ページへのアクセス、アカウント設定の変更、データ削除の前にユーザー確認を出します。こうした高リスク操作を AI に自動実行させないでください。

2. 呼び出し前に tool inputs を表示する：AI が実行しようとしている具体的なパラメータをユーザーに見せます。たとえば AI がボタンをクリックするなら、selector または座標を表示し、それが正しいか確認します。

3. 悪意あるデータ漏えいを防ぐ：tool output を確認し、パスワード、token、個人情報などの機密情報を AI が読み取って外部へ送らないようにします。tool が機密データを返した場合、AI にログへ書かせたり外部 server へ送信させたりしないでください。

4. timeout を設定する：ブラウザ操作は固まることがあり、リソースを消費したり他のタスクをブロックしたりします。各 tool call に 30 秒など妥当な timeout を設定し、超過したら自動キャンセルします。

5. tool usage を記録する：監査と追跡のために操作ログを残します。ログにはツール名、呼び出し時刻、入力パラメータ、出力結果、ユーザー承認記録を含めます。

6. tool results を検証する：スクリーンショット、console log、ネットワークリクエストが期待どおりか確認します。AI が「クリック成功」と報告しても、スクリーンショット上でボタンが押されていなければ切り分けが必要です。

server 側の安全おすすめ

Playwright MCP は公式 server なので自作する必要はありません。もし自分で MCP server を開発するなら、次を守ります。

1. 入力を検証する：URL、selector、入力内容を検証し、インジェクション攻撃を防ぎます。悪意ある URL や XSS payload を AI にそのまま渡させないでください。

2. アクセス制御を行う：アクセス可能なドメイン、ファイルパス、ブラウザ機能を制限します。たとえば内部 IP や機密パスへのアクセスを禁止します。

3. レート制限を入れる：AI が頻繁にツールを呼び出してリソースを使い切ったり、対象サイトにブロックされたりすることを防ぎます。1 分あたり最大 10 回など、妥当な制限を設定します。

4. 出力をサニタイズする：AI に返す前に機密情報を取り除きます。たとえば cookies の全文は返さず、必要な一部だけを返します。

---

最初の検証タスクと受け入れチェックリスト

設定が終わったら、簡単なタスクで Playwright MCP が正しく接続されているか検証します。

タスク例

AI にローカル preview ページ http://localhost:4321 を開かせ、ナビゲーションメニューをクリックし、スクリーンショットを撮り、console error を報告させます。

手順：

1. Playwright MCP が client（Claude Code、Codex、Cursor）に追加済みであることを確認します

2. Astro や Next.js などのローカル開発サーバーを起動し、http://localhost:4321 にアクセスできるようにします

3. Claude Code/Codex/Cursor に次の prompt を入力します。

   http://localhost:4321 を開き、ナビゲーションメニューの「記事」をクリックし、スクリーンショットを撮って、ページに console error があるか報告してください。

4. AI がブラウザツールを呼ぶか、ブラウザが起動するか、ページが開くかを観察します

受け入れチェックリスト

チェック項目	期待結果	確認方法
ブラウザが起動するか	headed mode ではブラウザウィンドウが開き、headless ではプロセスが起動する	UI またはプロセスマネージャーで確認
MCP server が接続されているか	client log に “Connected to MCP server” が表示される	client log を確認
accessibility snapshot が返るか	AI がナビゲーションメニューを見つけてクリックできる	AI 出力にクリック動作の説明が含まれる
ツール呼び出しに承認が必要か	設定次第。Codex では承認ダイアログが出ることがある	client が承認を求めるか観察
出力ディレクトリとログを追跡できるか	スクリーンショット、console log などが --output-dir に出る	指定ディレクトリを確認

失敗時の切り分け

AI がブラウザツールを呼ばない：

• MCP server が正しく追加されているか確認します（client log を見る）
• client が MCP Tool Search をサポートしているか確認します（Claude Code はデフォルトで有効）
• Node.js のバージョンが 18 以上か確認します

ブラウザは開くがボタンを見つけられない：

• Playwright MCP は screenshot ではなく accessibility tree を操作します。ページにセマンティックなラベルや ARIA 属性が不足していると、AI が認識できないことがあります
• ページの HTML 構造を確認し、ボタンに accessible label または role があるか見ます
• または --snapshot-mode パラメータで snapshot の詳細度を調整します

ブラウザが起動してすぐ閉じる：

• headless mode か、スクリプトが完了した可能性があります
• client log を確認し、ブラウザが正常に起動・終了したか見ます
• headed mode を使っているなら、AI が完了報告するまでブラウザウィンドウは開いたままになるはずです

---

Playwright CLI/SKILLS との取捨選択

Microsoft 公式 README は、coding agents の高スループットなコード作業では CLI + SKILLS のほうが向く場合があると明記しています。MCP は tool schema と accessibility tree をコンテキストに入れるため、token を消費するからです。MCP は、永続状態、豊富な introspection、継続するブラウザコンテキストが必要な探索的自動化、自動修復テスト、長時間タスクに向いています。

シーン別対照表

シーン	Playwright MCP 推奨	Playwright CLI + SKILLS 推奨
探索的自動化、自動修復テスト	はい、向いています	いいえ、向きません
長時間タスク、永続ブラウザコンテキストが必要	はい、向いています	いいえ、向きません
高スループットなコード作業	いいえ、コンテキスト消費が大きい	はい、向いています
コンテキスト消費を最小にしたい	いいえ、向きません	はい、向いています
すでに MCP client（Claude Code/Codex/Cursor）を使っている	はい、向いています	いいえ、向きません

この記事では SKILLS の具体的な使い方までは扱いません。後続記事で Codex のブラウザ検証実践を扱います。

---

まとめと次のステップ

この記事では、Claude Code、Codex、Cursor の 3 つの client で Playwright MCP を設定する方法、最初の検証タスクの受け入れチェックリスト、安全境界を扱いました。特に、browser_run_code_unsafe の RCE リスク、Profile モードによるログイン状態保存、--allowed-origins が安全境界ではない点が重要です。

設定差分まとめ

• Claude Code：claude mcp add コマンド、またはプロジェクトレベルの .mcp.json を使います。Tool Search はデフォルトで有効です
• Codex：codex mcp add コマンド、または config.toml を使います。approval_mode で高リスクツールを制御できます
• Cursor：Settings UI から設定します。前 2 つとは手順が異なります

次に読むもの

• ツール選定の横比較が必要：Browser Use vs Stagehand vs Playwright MCP：2026 年 AI ブラウザツール選定ガイド
• ログイン状態管理が必要：AI ブラウザログイン状態管理
• フロントエンドテストが必要：Playwright フロントエンドテストと検証
• Codex のブラウザ検証が必要：Codex ブラウザ検証実践
• 托管ブラウザ基盤が必要：托管ブラウザインフラ
• 安全設計が必要：AI ブラウザの安全設計と承認

Playwright MCP を設定したばかりなら、まず localhost:4321 の検証タスクを 1 回実行してください。ブラウザが起動し、AI がツールを呼び、スクリーンショットが指定ディレクトリに出力されることを確認します。問題があれば FAQ の順に切り分け、Node.js バージョン、client log、MCP server の接続状態を確認しましょう。