Playwright MCPをClaude Codeに登録すると、Claudeが自分で書いたコードの結果をブラウザで開き、画面の構造・コンソール・通信を読んで確かめられるようになります。登録自体は claude mcp add の1行で終わりますが、業務のリポジトリで使うには、どのスコープに置くか、どのツールを無確認で通すか、ログイン後の画面をどう再現するかを決める必要があります。この記事では、2026年11月14日時点の最新版である@playwright/mcp 0.0.85とClaude Codeの公式ドキュメントをもとに、登録から権限ルール、画面確認の手順、Claude in Chromeとの選び分けまでを作業順にまとめました。
まとめ：Claude CodeでPlaywright MCPを動かす前に決める4項目
- スコープ：個人の試用ならlocal（既定）、チームで同じ起動オプションをそろえるならprojectで
.mcp.jsonに書く。オプションを渡すときは--の区切りを入れる。 - 権限ルール：
mcp__playwright__で始まるツール名を、settings.jsonの allow・ask・deny に振り分ける。任意のコードを実行するbrowser_run_code_unsafeは deny に置く。 - ブラウザの状態：既定はヘッド有り・ディスク上のプロファイル。再現性を取るなら
--isolatedと--storage-stateの組み合わせにする。 - 画面確認の指示：CLAUDE.mdに「変更後に開くURL」「読むツール」「報告の形式」を書いておく。書かないとClaudeはシェルでスクリプトを組み始めることがある。
画面を持つWebアプリを日常的にClaude Codeで修正しているチームには、入れる価値があります。逆に、テストコードとして残したい確認や、毎回同じ手順で回す回帰確認は、Playwright Testで書いたほうが安く済みます。
Claude CodeからPlaywright MCPを呼ぶ構成と2026年11月時点の版
Claude CodeはPlaywright MCPを子プロセスとして起動し、標準入出力でツールを呼び出します。ブラウザを動かすのはPlaywright、どのツールを呼ぶか決めるのはClaudeです。
登録したサーバー名がmcp__playwright__のツール名になる仕組み
Claude Codeは、MCPサーバーのツールを mcp__<サーバー名>__<ツール名> の形で扱います。playwright という名前で登録すれば、ページを開くツールは mcp__playwright__browser_navigate という名前です。この名前は後で権限ルールを書くときの単位になるため、登録時のサーバー名をチーム内で統一しておくと設定ファイルを共有しやすくなります。Claude Codeの権限ドキュメントによると、サーバー名に . や空白が入ると _ に置き換えられるので、英小文字とハイフンだけの名前が無難です。
Playwright MCP 0.0.85と本体1.65.1の版が一致しない理由
npmの登録情報では、2026年11月14日時点の@playwright/mcpの最新は0.0.85（11月9日公開）、Playwright本体は1.65.1です。0.0.85を npx で起動してMCPの tools/list を送ったところ、サーバーが名乗る版は1.66.0-alpha-2026-11-09で、返ってきたツールは25個でした。@playwright/mcpは本体の開発版を固定で取り込む入口なので、@playwright/testの版とは一致しません。本体同梱の起動方法やツールの全体像はPlaywright MCPとは？使い方・料金・Dify連携の設定手順で解説しています。
本体の package.json は Node.js 20以上を要求しています。Node.js 18の端末では起動直後に終了し、Claude Code側には接続失敗としか出ません。
Claude in ChromeやCLIとPlaywright MCPを分ける条件
Claude Codeからブラウザを動かす手段は、Playwright MCPのほかに2つあります。Anthropicの拡張機能を使うClaude in Chromeと、Microsoftのplaywright-cliです。違いは「どのブラウザを動かすか」と「動く環境」に出ます。
| 比較項目 | Playwright MCP | Claude in Chrome | playwright-cli |
|---|---|---|---|
| 動かすブラウザ | 専用に起動する | 普段使いのChrome | 専用に起動する |
| ログイン状態 | storage-stateで渡す | そのまま共有 | セッションで保持 |
| APIキーやBedrock | 使える | 使えない | 使える |
| WSLやCI | headlessで動く | WSLは非対応 | 既定がheadless |
| Claudeからの呼び方 | MCPのツール | MCPのツール | Bashでコマンド |
Claude in Chromeのドキュメントでは、Pro・Max・Ultra・Team・Enterpriseのいずれかの直接契約と /login による認証が前提で、APIキーや長期トークンで認証したClaude Code、Bedrockなど他社クラウド経由の利用では動きません。普段のブラウザのログイン状態を使えるのは利点ですが、検証環境と本番の管理画面に同じブラウザでログインしている開発者には向きません。playwright-cliのREADMEは、ツール定義を読み込まない分だけトークン効率が良いとしてコーディングエージェントにはCLIを勧めています。比較の結論は最後の章で述べます。
claude mcp addの登録コマンドとlocal・project・userの選び方
登録はどのスコープでも1行です。決めるのは「誰の端末で有効にするか」と「起動オプションを渡すか」の2つです。
起動オプションを渡すときに必要な「–」区切りの登録コマンド例
Playwright MCPのREADMEに載っている登録コマンドは、オプションなしの形です。--headless などを付けるときは、Claude CodeのMCPドキュメントにあるとおり、サーバー名の後ろに -- を置きます。これを省くと、Claude Codeが --headless を自分のオプションとして解釈しようとします。
# READMEどおりの最小構成（local スコープ・ヘッド有り）
claude mcp add playwright npx @playwright/mcp@latest
# 起動オプションを付ける場合は -- の後ろに書く
claude mcp add playwright -- npx @playwright/mcp@latest --headless --isolated
# チームで共有する場合は project スコープ（.mcp.json に書かれる）
claude mcp add --scope project playwright -- npx @playwright/[email protected] --isolated
# 登録状態の確認
claude mcp listスコープは3種類です。local（既定）は自分だけ・今のプロジェクトだけ、projectはリポジトリの .mcp.json で全員と共有、userは自分の全プロジェクトで有効になります。ブラウザを操作するサーバーはプロジェクトごとに起動オプションが変わりやすいため、userに置くのは個人の調べ物に使う場合だけにしておくと混乱しません。スコープの優先順位や同名サーバーの扱いはClaude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例で詳しく扱っています。
チームで共有する.mcp.jsonにheadlessとisolatedを書く設定例
projectスコープで登録すると、リポジトリ直下に次のような .mcp.json ができます。手で書いても同じです。共有する設定では @latest ではなく版を固定し、更新はPRで行うと、ある日から全員の挙動が変わる事態を避けられます。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/[email protected]",
"--isolated",
"--viewport-size", "1280x720",
"--output-dir", ".playwright-mcp"
]
}
}
}--isolated はプロファイルをメモリに置き、セッションが閉じるとCookieやlocalStorageを捨てる指定です。付けない場合、READMEによればWindowsでは %USERPROFILE%\AppData\Local\ms-playwright 配下などにワークスペースごとのプロファイルが残ります。--output-dir はスクリーンショットなどの保存先で、指定したディレクトリは .gitignore に足しておきます。
/mcpとclaude mcp listで接続を確かめ失敗の原因を絞る手順
登録後にClaude Codeを起動し直し、/mcp でplaywrightが接続済みになっているか見ます。projectスコープの .mcp.json は、初回起動時に利用の承認が必要です。失敗と表示されたときは、次の順に確かめると原因に早く当たります。
node -vが20以上か。Playwright本体の要件で、18では起動直後に終了する。- ターミナルで
npx @playwright/[email protected] --helpを直接実行し、取得とヘルプ表示が通るか。社内プロキシでnpmの取得が止まっている場合はここで分かる。 - ヘッド有りのまま、画面の無い環境（WSLやコンテナ）で動かしていないか。この場合は
--headlessを足す。
3つとも問題が無ければ、同名サーバーの二重登録を claude mcp list で疑います。
settings.jsonでPlaywright MCPのツールを許可・確認・拒否に分ける
登録しただけの状態では、ブラウザ操作のたびに承認を求められます。全部を許可するのも、毎回承認するのも実務に合わないため、ツール単位で振り分けます。
mcp__playwright__の権限ルールの書き方とdenyが優先される評価順
Claude Codeの権限ルールは、deny、ask、allowの順に評価され、最初に一致したものが結果になります。権限ドキュメントには、範囲の狭いallowを書いても広いdenyに勝てないと明記されています。リポジトリで共有する .claude/settings.json の例です。
{
"permissions": {
"allow": [
"mcp__playwright__browser_navigate",
"mcp__playwright__browser_snapshot",
"mcp__playwright__browser_click",
"mcp__playwright__browser_type",
"mcp__playwright__browser_fill_form",
"mcp__playwright__browser_wait_for",
"mcp__playwright__browser_console_messages",
"mcp__playwright__browser_network_requests",
"mcp__playwright__browser_take_screenshot"
],
"ask": [
"mcp__playwright__browser_file_upload"
],
"deny": [
"mcp__playwright__browser_run_code_unsafe",
"mcp__playwright__browser_evaluate"
]
}
}サーバー全体を許可する書き方は mcp__playwright__* です。ただし mcp__* のようにサーバー名の部分を伏せたallowは無視され、何も許可されません。また、mcp__ で始まるルールに括弧で引数の条件を付けると、settingsファイルでは読み飛ばされる仕様です。「このURLだけ開いてよい」という書き方はできないため、接続先の制限は次のh3で扱うブラウザ側の設定と組み合わせます。権限ルール全般とサンドボックスの設定はClaude Codeのセキュリティ設定｜権限ルール・サンドボックス・管理設定で守る実装手順にまとめています。
RCE相当のbrowser_run_code_unsafeを拒否側に置く理由と影響
0.0.85の tools/list で返る説明文では、browser_run_code_unsafe は「Playwrightサーバーのプロセスで任意のJavaScriptを実行し、RCE（リモートコード実行）と同等」と書かれています。ページ上の文言に仕込まれた指示をClaudeが読み、このツールを呼ぶと、ブラウザの外にあるファイルやネットワークにもアクセスが可能です。browser_evaluate はページ内でJavaScriptを評価するツールで、こちらはブラウザの中に閉じますが、ログイン済みの画面で実行されるとセッションを使った操作ができてしまいます。
この2つを拒否しても、画面の確認に困る場面はほとんどありません。要素の状態はスナップショットで、エラーはコンソールで読めるからです。browser_file_upload は端末上の任意のパスを受け取るため、askに置いて毎回確認します。Playwright MCPの既知の脆弱性と社内で許可するときの論点はPlaywright MCPのセキュリティ｜危険性とCVE-2025-9611対策で整理しています。
–allowed-originsが安全境界にならない点と接続先の絞り方
Playwright MCPには、ブラウザが通信してよいオリジンをセミコロン区切りで指定する --allowed-origins があります。開発中は http://localhost:3000 と検証環境だけに絞っておくと、Claudeが調べ物のつもりで外部サイトを開く事故を減らせます。
# ローカルと検証環境だけに通信先を絞る
claude mcp add playwright -- npx @playwright/[email protected] --isolated \
--allowed-origins "http://localhost:3000;https://stg.example.com"ただし公式の設定オプション一覧とREADMEは、この指定がセキュリティ境界ではなく、リダイレクトにも効かないと明記しています。意図しないアクセスを減らす仕組みとして使い、本番環境の資格情報を渡さない、ブラウザを動かす端末を分けるといった対策と組み合わせてください。
実装後にClaude Codeへ画面を確かめさせる検証ループの組み方
Playwright MCPを入れる目的の多くは、Claudeが「直しました」と言う前に、自分で画面を開いて確かめさせることです。そのためには、確認の手順をClaudeが毎回読む場所に書いておきます。
CLAUDE.mdに書く画面確認の手順とスナップショットの読ませ方
ツール名を指定しないと、Claudeはシェルで一時的なPlaywrightスクリプトを書いて実行しようとすることがあります。プロジェクトのCLAUDE.mdに、確認の手順を具体的に書いておくのが確実です。
## 画面の変更を確認する手順
- UI を変更したら、完了と報告する前に playwright の MCP ツールで確認する
- 開発サーバーは npm run dev で起動し、http://localhost:3000 を開く
- 要素の確認は browser_snapshot を使い、スクリーンショットは見た目の崩れを疑うときだけ撮る
- browser_console_messages で error が出ていないこと、browser_network_requests で 4xx・5xx が無いことを確認する
- 報告には「開いた URL」「確認した操作」「コンソールのエラー件数」を書く
- ブラウザで確認できなかった場合は、確認できなかったと書くスナップショットはアクセシビリティツリーをテキストで返すので、スクリーンショットより少ないトークンで要素の名前と状態を読めます。最後の2行は、確認を省いて「動作確認済み」と書く報告を防ぐための指示です。ディレクトリ単位で指示を分けたい場合はClaude Code rulesの書き方｜.claude/rulesのpaths指定とCLAUDE.mdの使い分けの方法で、フロントエンドのディレクトリにだけ適用できます。
ログイン後の画面を–storage-stateで再現する手順とファイルの扱い
--isolated にすると毎回ログアウト状態から始まるため、管理画面の確認では毎回ログイン操作が入ります。ログイン済みのCookieとlocalStorageをファイルに保存し、起動時に読ませるとログイン操作を省ける仕組みです。保存にはPlaywrightのcodegenの --save-storage が使えます。
# 1. ブラウザが開くので検証環境に手でログインし、ウィンドウを閉じる
npx playwright codegen --save-storage=.auth/stg.json https://stg.example.com/login
# 2. 保存した状態を読み込んで Playwright MCP を起動する
claude mcp add playwright -- npx @playwright/[email protected] --isolated \
--storage-state .auth/stg.json公式ドキュメントは、このファイルが機密情報を含むためローカルでだけ使い、.gitignore に入れるよう注意しています。保存するのは検証環境のテストアカウントに限り、本番のセッションは保存しないでください。
claude -pと–mcp-configで変更後の画面確認を流すコマンド例
対話しない claude -p でも、CLIリファレンスの --mcp-config でサーバーを渡せます。--strict-mcp-config を付ければ、リポジトリや個人の設定にある他のMCPサーバーを読み込みません。PRを出す前に手元で画面確認だけを流す例です。
# ci-mcp.json の中身は .mcp.json と同じ形で、args に --headless を足したもの
claude -p "http://localhost:3000/orders を開き、注文一覧の表と検索欄が表示されること、コンソールに error が無いことを確認して結果を箇条書きで報告して" \
--strict-mcp-config --mcp-config ./ci-mcp.json \
--allowedTools "mcp__playwright__browser_navigate" "mcp__playwright__browser_snapshot" "mcp__playwright__browser_console_messages" \
--max-turns 10 --output-format json--allowedTools に読み取り系の3つだけを渡しているので、対話の無い -p ではクリックや入力が許可されず、実行されません。--max-turns は往復回数の上限で、画面が想定と違ったときに探索が長引くのを止めるための指定です。この確認は結果の文章をClaudeが書く仕組みなので、合否をCIのゲートにするのは避け、PRのコメントに貼る程度にとどめます。合否を機械で判定したい確認は、Playwright Testのテストとして書きます。
Claude CodeでPlaywright MCPを使う場面と見送る場面の判断基準
Playwright MCPは、決まった手順を繰り返す道具ではなく、Claudeが状態を見ながら次の操作を決めるための道具です。採否はこの性質に合う作業かどうかで決まります。
スナップショットのトークン量とMCP出力上限から見た向かない画面
Claude Codeは、MCPツールの出力が1万トークンを超えると警告を出し、既定では2万5,000トークンで打ち切ります（MCPドキュメント、環境変数 MAX_MCP_OUTPUT_TOKENS で変更可）。行数の多い一覧表や、要素が数千ある管理画面では、スナップショット1回で上限に近づきます。こうした画面では、browser_snapshot の depth や target で範囲を絞るよう指示するか、確認対象の部分だけを表示するURLを用意します。canvasで描くグラフのように、アクセシビリティツリーに中身が出ない画面も、スナップショットでは確かめられません。
Playwright MCPを採用する条件とCLIやテストへ移る場面
採用してよいのは、ClaudeにUIの修正を任せる頻度が高く、修正のたびに人が画面を開いて確かめている手間が目に見えて大きいチームです。検証環境とテストアカウントがあり、上の権限ルールをリポジトリで共有できることも条件になります。APIキー契約やBedrock経由のClaude Code、WSLやコンテナで開発している環境では、Claude in Chromeが使えないため、Playwright MCPが現実的な選択肢になります。
見送るのは次の3つの場面です。第一に、Claude Codeだけで使い、MCPでしかツールを呼べないクライアントと設定を共有する必要が無い場合。この条件ならトークン消費の少ないplaywright-cliを先に試します。第二に、毎回同じ手順を通す回帰確認。Claudeに毎回探索させるより、テストコードにしてCIで回すほうが速く、結果もぶれません。計画からテスト生成までをエージェントに任せる方法はPlaywright Agentsの使い方：init-agentsの導入とplanner・generator・healerの実行手順で扱っています。第三に、決済や外部送信を伴う画面を、サンドボックスの無い環境で操作させる場合です。社内の業務システムにブラウザを操作するエージェントを組み込み、権限設計や監査ログまで含めて整えたい場合は、AIエージェント開発としてご相談いただけます。
よくある質問
Claude CodeでPlaywright MCPを使い始めるときによく確認される点を、2026年11月14日時点の公式ドキュメントと0.0.85の実測に沿って回答します。
Claude CodeでPlaywright MCPを使うのに料金はかかりますか？
Playwright MCPはApache-2.0のオープンソースで、利用料はかかりません。費用はClaude Code側の契約で決まり、サブスクリプションの利用枠か、APIの従量課金でトークン分を払います。大きな管理画面を何度も読ませると、その分だけ消費が増えます。
claude mcp addで登録したのに接続失敗と表示されるのはなぜですか？
多いのは、Node.jsが20未満、画面の無い環境でヘッド有りのまま起動している、起動オプションの前に -- を入れずに登録した、の3つです。本文の確認手順の順に見ていけば、たいていはどれかに当たります。
ブラウザの画面を出さずにClaude Codeから動かせますか？
動かせます。登録時に claude mcp add playwright -- npx @playwright/mcp@latest --headless のように --headless を付けるか、環境変数 PLAYWRIGHT_MCP_HEADLESS を設定します。既定はヘッド有りなので、WSLやコンテナ、CIでは必ず指定してください。
Claude in ChromeとPlaywright MCPはどちらを使えばよいですか？
普段使いのChromeのログイン状態をそのまま使いたく、Claudeの直接契約のプランで /login しているならClaude in Chromeが手軽です。APIキーやBedrock経由で使っている、WSLやCIで動かしたい、検証用のまっさらなブラウザで確かめたい、のいずれかに当てはまるならPlaywright MCPを選びます。両方を入れて用途で分けることもできます。
Playwright MCPで確認した操作をテストコードとして残せますか？
MCPでの操作はその場の確認で、テストファイルは自動では残りません。残したい場合は、確認できた手順をもとにPlaywright Testのテストを書くようClaudeに依頼するか、テストの計画・生成・修復をまとめて扱うPlaywright Test Agentsを使います。Test Agentsはテストランナー直結の別のMCPサーバーを使うため、Playwright MCPとは登録も別になります。
関連記事
- Playwright MCPとは？使い方・料金・Dify連携の設定手順【Playwright 1.64対応】：Playwright MCPの仕組み・25ツール・他クライアントへの登録
- Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】：スコープの優先順位と認証付きMCPサーバーの登録
- Playwright Agentsの使い方：init-agentsの導入とplanner・generator・healerの実行手順【1.65対応】：画面確認をテストコードとして残す方法
- Claude Codeの使い方｜インストールから権限・CLAUDE.md設定、初日の進め方まで：Claude Code自体の導入とCLAUDE.mdの基本
- Browser Useとは？使い方・料金とCLI 3.0・Playwright MCPとの違い【0.13.14対応】：Playwright MCP以外のブラウザ操作エージェントとの比較
