Playwright MCPでAIエージェントにブラウザ検証を任せる：snapshot・profile・権限の分け方

3行まとめ

Snapshot

アクセシビリティツリーで安定操作します。

Profile

ログイン状態とcookieを分けて扱います。

Permission

unsafe codeやfile accessを制限します。

ブラウザを触れるMCPは、便利さと権限を一緒に見ます。

• Playwright MCPは、AIエージェントがaccessibility snapshotを使ってブラウザを操作できる便利な入口ですが、ログイン状態、file access、unsafe code実行を同じ権限として扱うと危険です。
• 最初はpublic page、isolated profile、snapshot中心の確認から始め、必要になった段階でstorage state、network/console確認、extension modeを分けて開きます。
• browser_run_code_unsafeのような任意JavaScript実行はRCE相当として扱い、trusted MCP clientだけに限定します。

本文の事実確認には、Playwright MCP公式Docs、microsoft/playwright-mcp README、Playwrightのbrowser connection Docsを使っています。Xで見かけるブラウザMCP、AI coding agentのE2E確認、token効率、ログイン状態の扱いへの投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

用途

確認、デバッグ、ログイン操作を分けます。

状態

persistent、isolated、extensionを選びます。

安全

unsafe codeとfile accessを制限します。

運用

AI agentに任せる範囲を決めます。

Playwright MCPは設定より先に運用範囲を決めます。

• Playwright MCPをAIエージェントへ入れる前の用途分け
• accessibility snapshotとscreenshotの使い分け
• persistent、isolated、storage state、extension modeの違い
• headless/headed、browser selection、HTTP transportの見方
• network mocking、console確認をいつ使うか
• unsafe code、file access、origin制限をどう扱うか

Playwright MCPは、AIエージェントに「ブラウザで確認して」と頼めるようにする強力な道具です。ただし、ブラウザはログイン済みsession、cookie、localStorage、外部API、file accessに近い場所でもあります。

この記事では、Playwright MCPをE2E確認の補助として使うときに、便利さと権限を分けて整理します。

前提知識

項目	内容	見方
Install		npxでMCP serverを起動します。
Snapshot		pageの構造をrefs付きで返します。
Profile		永続、isolated、extensionを選びます。
Unsafe code		trusted clientだけに限定します。

ブラウザ操作は、状態と実行権限を別々に管理します。

Playwright MCP公式Docsでは、Playwright MCP serverがModel Context Protocolを通じてbrowser automation capabilitiesを提供し、LLMがstructured accessibility snapshotsを使ってweb pageとやり取りできると説明されています。

標準設定は、MCP clientへnpx @playwright/mcp@latestを追加する形です。VS Code、Cursor、Claude Code、Claude Desktop、Windsurf、Cline、Codex、Copilot CLIなど、多くのclientで使える説明があります。

この記事の扱う範囲

項目	役割
accessibility snapshot	page elements、roles、text、refsを構造として返す
browser interaction	navigation、click、type、form、tabs、dialogs
screenshot	画面の証跡
storage state	cookieやlocalStorageを保存/復元
profile mode	persistent、isolated、extension
unsafe code	Playwright server processで任意JSを実行
network/console	request、mock、browser consoleの確認

条件

2026年5月31日時点で公開されているPlaywright MCP公式DocsとREADMEを確認しています。導入時には、利用するMCP client、Playwright MCP version、実行OS、ブラウザ、CI環境を確認してください。

注意点

この記事は、AIエージェントに本番操作やログイン済みアカウントを無条件に渡すための記事ではありません。まず確認範囲を小さくし、必要な権限だけを段階的に開く前提です。

まず3つの用途に分ける

項目	内容	見方
UI確認		snapshotとscreenshotで確認します。
E2E補助		form入力、click、consoleを使います。
ログイン要		storage stateかextensionを検討します。
高度操作		unsafe codeは信頼端末に限定。

全部入りの設定から始めず、必要な用途だけ開きます。

Playwright MCPは、最初に用途を3つに分けます。

用途	任せること	最初の設定
UI確認	page表示、click、form入力、screenshot	public page、isolated寄り
E2E補助	失敗再現、console、network、mock	test/staging環境
ログイン要操作	SSO/2FA後の確認、既存tab操作	storage stateまたはextension mode

全部入りで始めない

最初からログイン済みbrowser、persistent profile、network mocking、unsafe code、file accessを全部開くと、何が危険だったのか追えません。

まずはpublic pageでsnapshot操作を確認します。次にtest/staging環境でform入力やscreenshotを使います。ログイン状態が必要になってから、storage stateやextension modeを検討します。

MCPは正式E2Eの代わりではない

Playwright MCPは、AIエージェントによるブラウザ確認に向いています。一方で、CIで安定して回す正式E2Eは、Playwright Testとしてコード化する方が再現性を取りやすいです。

判断基準

「agentに一度確認させたい」のか、「毎回CIで保証したい」のかを分けます。前者はMCP、後者はPlaywright Testです。

accessibility snapshotで操作する

Roles

heading、textbox、buttonなどを読みます。

Refs

refを使ってclickやtypeを行います。

Stable

座標より安定しやすい操作です。

Visual

必要な時だけscreenshotを使います。

操作はsnapshot、画面の証跡はscreenshotと分けます。

Playwright MCP公式Docsでは、pageのaccessibility treeを使い、roles、text、refsを含むstructured snapshotを返すと説明されています。LLMはrefを使ってtextboxへ入力したりcheckboxを操作したりします。

snapshotの利点

利点	内容
構造で読める	heading、textbox、buttonなどのroleが見える
refで操作できる	座標ではなくelement refを使える
視覚依存が減る	screenshotだけより操作が安定しやすい
テキスト確認しやすい	form labelやbutton textを拾いやすい

screenshotと役割を分ける

snapshotは操作用、screenshotは画面の証跡用です。Playwright MCP公式Docsでも、screenshotはcurrent pageやspecific elementsのvisual verificationに使う説明があります。

余白、重なり、画面上の状態はscreenshotで確認します。buttonを押す、inputへ入力する、dialogを閉じる、といった操作はsnapshotのrefsを使います。

agentへの依頼例

https://example.test/login を開いて、ログインフォームのlabel、button、validation messageを確認してください。
実行した操作と、見つけたconsole errorを最後にまとめてください。

注意点

snapshotに出ないcanvas、複雑なvisual、custom widgetは、操作しづらい場合があります。その場合はscreenshot、manual確認、Playwright Testのlocator調整へ切り替えます。

profileとstorage stateを分ける

項目	内容	見方
Persistent		既定でprojectごとにprofileを保存。
Isolated		毎回freshなsessionで始めます。
Storage state		初期ログイン状態を読み込みます。
Cookie tools		必要なcookieだけ管理します。

ログイン状態は便利ですが、権限の持ち越しにもなります。

Playwright MCP公式Docsでは、profile modeとしてpersistent、isolated、browser extensionが説明されています。persistentはlogin stateやcookiesをsession間で保持し、isolatedはfresh sessionとして始められます。storage stateを読み込むこともできます。

profile modeの見方

mode	向く用途	注意
persistent	同じprojectでログイン状態を使い回す	権限も持ち越す
isolated	毎回cleanな確認	毎回loginが必要
storage state	初期状態を明示して開始	state fileの管理が必要
extension	既存browser sessionを使う	実アカウント権限を渡す

最初はisolated寄り

権限の持ち越しを避けるなら、最初はisolated寄りで始めます。ログインが必要なときだけ、staging用アカウントのstorage stateを使います。

persistentは便利だが監査しにくい

persistent profileは、毎回ログインしなくてよいので便利です。ただし、前回のcookie、localStorage、feature flag、テストデータが残るため、再現性と監査性は落ちます。

state fileの扱い

storage state fileにはcookieや認証情報に近い情報が含まれる可能性があります。repoへcommitしない、CI secretとして扱う、staging専用にする、期限を短くする、という運用にします。

headlessとheadedを使い分ける

Headed

既定。動きを見ながら確認します。

Headless

CIや自動確認に寄せます。

Browser

chrome、firefox、webkit等を選びます。

Port

displayなし環境ではserver分離も検討。

人が見る検証と自動で回す検証は設定を分けます。

Playwright MCP公式Docsでは、既定ではheaded modeで動き、--headlessを付けるとheadlessで実行できると説明されています。browser selectionではchrome、firefox、webkit、msedgeなどを選べます。

headedに向く場面

• 人間がagentの操作を見たい
• UI崩れを目視したい
• ログインや2FAが絡む
• agentの誤操作を早めに止めたい

headlessに向く場面

• CI寄りの確認
• screenshotやconsoleだけ取る
• public pageの定型確認
• server環境で動かす

displayがない環境

Playwright MCP READMEでは、displayなし環境やIDE worker processからheaded browserを動かす場合、MCP serverをHTTP transportで別途起動する例が説明されています。

npx @playwright/mcp@latest --port 8931

client側はHTTP endpointへ向けます。ローカルのIDE workerとbrowser実行環境を分けたい場合に検討します。

実務上の目安

初回導入はheadedで挙動を見ます。定型確認へ寄せる段階でheadlessとisolatedを使います。

extension modeはSSO向けに限定する

項目	内容	見方
SSO		複雑なlogin flowを避けられます。
2FA		既存sessionを再利用できます。
Extensions		依存するbrowser extensionを使います。
Risk		実アカウント権限をagentへ渡します。

extension modeは便利ですが、ログイン済み権限を渡す判断です。

Playwrightのbrowser connection Docsでは、Playwright Extensionを使うと既存browser tabs、logged-in sessions、cookies、installed extensionsを再利用できると説明されています。SSO、2FA、browser extension依存、既存tab操作に向く説明があります。

extension modeに向く場面

場面	理由
SSO	複雑なlogin flowを避けられる
2FA	既存sessionを再利用できる
browser extension依存	installed extensionsを使える
既存tab	開いている画面をそのまま確認できる

extension modeのリスク

extension modeは、ログイン済みbrowserをagentへ渡す判断です。社内管理画面、本番DB dashboard、決済画面、顧客情報画面が同じbrowserに開けるなら、権限はかなり大きくなります。

使うなら分ける

extension modeを使うなら、普段使いのbrowserではなく検証用browser profileを作ります。staging account、権限の弱いrole、必要なtabだけ、という状態にします。

判断基準

「このbrowserでagentが誤clickしても問題ないか」と考えます。問題があるならextension modeではなく、isolated + storage state + staging環境へ寄せます。

network mockingとconsole確認の使いどころ

Requests

page load後のrequestを見ます。

Mock

API responseを差し替えます。

Console

browser consoleを確認します。

Screenshots

最終状態の証跡を残します。

E2E失敗はUI、network、consoleを並べて追います。

Playwright MCP公式Docsでは、network requestsの確認、mock routes、browser console outputへのアクセスが説明されています。E2E失敗の原因を切り分けるときに使います。

使いどころ

機能	見ること
request list	APIが呼ばれたか、statusは何か
mock route	backend依存を外してUIを確認
console output	client error、warning、hydration issue
screenshot	最終状態、画面の証跡

mockは本番へ向けない

mock routeは検証に便利ですが、production画面で使うと実際の挙動を隠します。stagingやlocalで使い、最終確認ではmockなしの挙動も見ます。

console errorを成果物に残す

AI agentに確認を頼むなら、最後に「操作、確認結果、console error、network error、screenshotの有無」をまとめさせます。これはGitHub ActionsでAIエージェント作業ログを残すで扱ったログ整理にもつながります。

実務例

「ログイン後にsettings pageを開き、API 500、console error、画面上の不自然な状態がないか確認して」と頼むと、UI、network、consoleを一度に見られます。

unsafe codeとfile accessを制限する

項目	内容	見方
run code		任意JS実行はRCE相当として扱います。
file access		workspace外のfile accessは閉じます。
Origins		許可originを明確にします。
Clients		trusted MCP clientだけに限定します。

便利な機能ほど、最初は閉じて必要時だけ開きます。

Playwright MCP公式Docsでは、browser_run_code_unsafeはPlaywright server processでarbitrary JavaScriptを実行するため、RCE-equivalentであり、trusted MCP clientsだけで有効にするよう注意されています。

READMEでは、--allow-unrestricted-file-accessがworkspace root外へのfile accessやfile URLへのaccessを許可する説明もあります。既定ではfile system accessはworkspace root directoriesへ制限され、file URL navigationはblockされる説明です。

強い権限

機能	リスク
browser_run_code_unsafe	任意JS実行、RCE相当
unrestricted file access	workspace外のfile参照
extension mode	ログイン済みbrowser権限
persistent profile	cookieやlocalStorageの持ち越し
network mock	実際の挙動を隠す

最初は閉じる

最初はunsafe code、unrestricted file access、extension modeを使わずに始めます。必要になったら、trusted client、staging環境、検証用profile、限定originの条件で開きます。

allowed originsを過信しない

READMEでは、allowed originsに関する注意として、trusted originsのallow指定はsecurity boundaryとしては扱えず、redirectにも影響しない説明があります。origin設定だけで安全だと思わない方がよいです。

実務上のルール

AIエージェントにブラウザを渡すなら、MCP設定をAGENTS.mdやrepo docsに明記します。どのclientで、どのprofileで、どのoriginまで、unsafe codeを許すかを書きます。

最小設定の形

項目	内容	見方
Standard		npx @playwright/mcp@latestで開始。
Isolated		必要ならfresh sessionにします。
Headless		自動確認ではheadlessを検討。
No unsafe		run codeは最初は使いません。

まずは画面確認と入力操作だけを任せます。

最小は、標準設定から始めます。

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

headlessにする

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

isolatedにする

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

Codex CLIの例

microsoft/playwright-mcp READMEでは、Codex CLIで次のように追加する例があります。

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

または~/.codex/config.tomlにMCP serverを追加します。

最初の確認プロンプト

https://demo.playwright.dev/todomvc を開き、todoを2件追加してください。
操作ごとに何をクリック/入力したか、最後に画面上のtodo件数をまとめてください。
unsafe codeは使わず、snapshot操作だけで進めてください。

導入初週の進め方

1. 1日目

   public pageでsnapshot操作を試す。

2. 2日目

   form入力とscreenshotを確認。

3. 3日目

   isolated/profileを切り替える。

4. 5日目

   network/consoleを失敗調査に使う。

5. 7日目

   extensionやunsafe要否をレビュー。

最初からログイン済みbrowserやunsafe codeを渡さないようにします。

Playwright MCPは、権限を段階的に開きます。

1日目: public pageでsnapshot操作

demo pageや社内の公開確認ページで、navigation、click、type、snapshotを試します。ログインやfile accessは扱いません。

2日目: form入力とscreenshot

staging環境でform入力、validation message、screenshotを確認します。agentの操作ログを残します。

3日目: isolatedとpersistentを比較

同じtaskをisolatedとpersistentで試し、再現性とログインの手間を比較します。persistentは便利ですが、状態が残ることを確認します。

5日目: networkとconsoleを失敗調査に使う

API status、console error、screenshotをセットで確認します。mock routeはlocal/stagingだけで使います。

7日目: extensionとunsafe codeの要否をレビュー

SSO/2FAが本当に必要か、storage stateで足りるかを見ます。browser_run_code_unsafeが必要なら、trusted client、検証用profile、staging環境に限定します。

評価するログ

• agentがsnapshot refsで安定して操作できたか
• ログイン状態が意図せず持ち越されていないか
• screenshot、console、networkが証跡として残ったか
• unsafe codeやunrestricted file accessを使わずに済んだか

FAQ

MCP or Test?

確認補助と正式E2Eを分けます。

Login?

storage stateかextensionを選びます。

Unsafe?

trusted clientだけに限定します。

CI?

headlessとisolatedを基本にします。

迷ったら、agentへ渡す権限の大きさを先に見ます。

Playwright MCPはPlaywright Testの代わりですか

代わりではありません。Playwright MCPはAIエージェントがブラウザ確認を行う入口です。CIで毎回保証するテストはPlaywright Testとして書きます。

screenshotだけで操作できますか

操作はaccessibility snapshotのrefsを使う方が安定します。screenshotは画面の証跡に使います。

ログイン済みbrowserを使ってよいですか

使えますが、権限が大きいです。まずstorage stateやstaging accountを検討し、extension modeはSSO/2FAなど本当に必要な場面に限定します。

browser_run_code_unsafeは使ってよいですか

公式DocsではRCE-equivalentとして扱われています。trusted MCP clientだけに限定し、最初の導入では使わない方が安全です。

MCP経由のブラウザ操作ログはどう残しますか

agentに、操作、確認結果、console/network error、screenshot有無、未確認項目を最後にまとめさせます。CIで動かすならartifactやjob summaryへ残す設計も有効です。

MCPの権限設計はどこから考えますか

read-only、staging、isolatedから始めます。MCP全体の権限設計は、MCP仕様・SDK更新時の実務影響チェックとTypeScriptで作る最小MCP Serverも合わせて確認してください。

---

次に読むなら

参照した主な情報源

• Playwright Docs: Playwright MCP

https://playwright.dev/docs/getting-started-mcp

• GitHub: microsoft/playwright-mcp README

https://github.com/microsoft/playwright-mcp

• Playwright Docs: Connecting to Browsers

https://playwright.dev/mcp/configuration/browser-extension

• Playwright GitHub README

https://github.com/microsoft/playwright

次に読むなら

更新履歴

1. 2026年5月31日

   Playwright MCP公式Docs、microsoft/playwright-mcp README、browser connection Docsを確認して初版を作成しました。

導入時には最新Docsと利用clientのMCP設定を確認してください。

• 2026年5月31日: Playwright MCP公式Docs、microsoft/playwright-mcp README、browser connection Docsを確認し、初版を公開しました。