この記事の要点
Playwright MCP は、Playwright を使ったブラウザ操作を MCP サーバーとして提供するものです。特徴は「スクリーンショットではなく構造化されたアクセシビリティスナップショットでページを扱う」点で、公式 README はこれを「screenshots や visually-tuned models を必要としない」方式だと説明しています（Microsoft「Playwright MCP」README（2026年9月18日閲覧））。Claude Code 側の登録は README に載っている次の1行です。
claude mcp add playwright npx @playwright/mcp@latest
ただし、この1行だけで E2E テストが回るわけではありません。どのプロファイルで起動するか、ページをどう読ませるか、どのツールを許可してどのツールを止めるか、そもそも MCP と CLI のどちらを使うか。これらを決めないと、ログイン状態が消えたり、スナップショットで文脈が埋まったり、browser_run_code_unsafe のような強いツールが素通りしたりします。この記事はその順番で7手順に並べたものです。
- Playwright MCP が何をしているのかを、アクセシビリティツリーとスクリーンショットの違いで押さえる
- 登録の1行を決める。stdio・Docker・HTTP の3経路と
--の位置 - 起動オプションを絞る。
--isolated・--storage-state・--headlessとプロファイルの衝突 - ページを読む。
browser_snapshot・browser_find・browser_take_screenshotの使い分け - 操作する。
refの扱いとbrowser_click・browser_fill_form・browser_wait_for - 権限を切る。
mcp__playwright__の許可設計とフック - MCP か CLI と Skills か。トークン効率で選び分ける
対象読者は、ターミナルの Claude Code を日常的に使っていて、ブラウザ操作や E2E テストを手元のエージェントに任せたい開発者・QA エンジニアです。コマンド・フラグ・ツール名・バージョン条件は、すべて Microsoft と Anthropic の公式ドキュメントに記載のある値だけを書いています。業務への当てはめは末尾に「想定モデル事例」として分け、実在の導入事例ではないことを明記しています。
1. Playwright MCPは何をしているのか。アクセシビリティツリーで操作する
Playwright MCP は、Playwright のブラウザ自動化機能を MCP（Model Context Protocol）のツールとして公開するサーバーです。LLM はページを「構造化されたアクセシビリティスナップショット」越しに触ります（Microsoft「Playwright MCP」README（2026年9月18日閲覧））。
スクリーンショット方式との違い
公式 README が挙げる特徴は3つです。ピクセル入力ではなく Playwright のアクセシビリティツリーを使うので速くて軽いこと、視覚モデルを必要とせず構造データだけで動くこと、そしてスクリーンショット方式にありがちな曖昧さを避けた決定的なツール適用ができることです。
言い換えると、エージェントは「画像を見て座標クリックする」のではなく、スナップショットに現れた要素の参照（ref）を指して操作します。座標クリックはレイアウトが少し変わるだけで壊れますが、構造データを指す操作は壊れ方が読めます。E2E テストを書かせる用途で Playwright MCP が選ばれるのは、この決定性が理由です。
動作要件はNode.js 18以上
要件は Node.js 18 以降、そして MCP クライアントです。README はクライアントの例として VS Code、Cursor、Windsurf、Claude Desktop、Goose、Grok、Junie などを挙げており、Claude Code 用のインストール手順も独立した節として載っています。
ツールの一覧は「読む」「操作する」「危ない」の3層で捉える
提供されるツールは 30 個近くありますが、設計上は3層に分けて捉えると扱いやすくなります。
| 層 | 代表的なツール | Read-only |
|---|---|---|
| 読む | browser_snapshot / browser_find / browser_take_screenshot | true |
| 操作する | browser_navigate / browser_click / browser_fill_form / browser_wait_for | false |
| 危ない | browser_run_code_unsafe / browser_evaluate | false |
README の各ツール定義には Read-only: true / false が明記されています。この区分がそのまま第6手順の権限設計の下敷きになります。
2. 登録の1行を決める。stdio・Docker・HTTPの3経路
Playwright MCP を Claude Code に登録する経路は3つあります。どれを選ぶかで、ブラウザがどこで動くか、ヘッドありで見えるかが変わります。
経路1：npxで直接起動する（README掲載の1行）
README の Claude Code 向け手順は次の1行です（Microsoft「Playwright MCP」README（2026年9月18日閲覧））。
claude mcp add playwright npx @playwright/mcp@latest
ここで注意したいのが -- の扱いです。Anthropic 公式ドキュメントは、stdio サーバーでは --（ダブルダッシュ）が Claude Code 自身のオプション（--transport・--env・--scope）とサーバーを起動するコマンドを区切ると説明しています。-- の後ろはそのままサーバーへ渡されます。逆に -- を書かないと、Claude Code はサーバー側のフラグを自分のオプションとして解釈しようとします（Anthropic「Connect Claude Code to tools via MCP」（2026年9月18日閲覧））。
つまり、第3手順で扱う --headless や --isolated を渡すなら、次の形にしておくのが安全です。
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest --isolated --headless
経路2：Dockerコンテナで動かす
README の Security 節には Docker 構成が載っています。ただし Docker 実装は現時点で headless chromium のみ対応と明記されている点に注意してください。
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
}
}
}
MCP クライアントにコンテナを起動させるのではなく、常駐サービスとして動かす形も README に載っています。その場合はポート 8931 で待ち受け、任意の MCP クライアントから到達できます。
経路3：HTTPトランスポートで別プロセスに置く
ディスプレイのない環境でヘッドありブラウザを動かす場合や、IDE のワーカープロセスから使う場合は、DISPLAY のある環境で MCP サーバーを起動し --port を渡します。
npx @playwright/mcp@latest --port 8931
クライアント側は url に http://localhost:8931/mcp を指定します。Claude Code から登録するなら claude mcp add --transport http playwright http://localhost:8931/mcp の形になります。
スコープは先に決める
Claude Code の MCP 設定には local・project・user の3スコープがあり、claude mcp add は --scope project か --scope user を付けない限り local スコープへ書き込みます。プロジェクトスコープ（.mcp.json）のサーバーは、対話セッションで使う前に承認プロンプトが出ます。承認の選択をやり直すには claude mcp reset-project-choices を実行します（Anthropic「Connect Claude Code to tools via MCP」（2026年9月18日閲覧））。
チームのリポジトリに .mcp.json を置いて配る設計は、Claude Code管理MCP配布の手順とMCP認証のチーム配布で扱っている前提がそのまま当てはまります。
3. 起動オプションを絞る。isolated・storage-state・headless
Playwright MCP のオプションは README の表に一覧があり、すべて対応する環境変数も定義されています。ここでは E2E テスト運用で最初に決めるべき3つに絞ります。
プロファイルは既定で永続、置き場はOSごとに決まっている
既定では通常のブラウザと同じように永続プロファイルを使い、ログイン情報がそこに残ります。保存先は OS ごとに決まっており、--user-data-dir で上書きできます（Microsoft「Playwright MCP」README（2026年9月18日閲覧））。
# macOS
~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}
# Linux
~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}
{workspace-hash} は MCP クライアントのワークスペースルートから導かれるので、プロジェクトごとに別プロファイルになります。ここで README が IMPORTANT として警告しているのが、永続プロファイルは一度に1つのブラウザインスタンスしか使えない点です。同じワークスペースを共有する複数の MCP クライアントは衝突します。並列で走らせるなら、追加のクライアントは --isolated で起動するか、別の --user-data-dir を指すようにします。
Claude Code で複数セッションを並べる運用をしているなら、この制約は最初に踏みます。テスト用のセッションは --isolated 側へ寄せるのが素直です。
テストは isolated と storage-state の組み合わせに寄せる
--isolated はプロファイルをメモリ上に保持し、ディスクへ保存しません。ブラウザを閉じるたびにセッションのストレージ状態は失われます。ログイン済みの状態から始めたいなら、--storage-state で保存済みのストレージ状態ファイルを読み込ませます。ストレージ状態そのものの作り方は Playwright 本体のドキュメントに整理されています（Playwright「Authentication」（2026年9月18日閲覧））。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}
認証情報そのものを渡したい場合は --secrets があります。dotenv 形式のファイルパスを渡す形です。リポジトリに直接書かず、このファイル経由にしておくと取り回しが楽になります。
headlessは既定ではない
Playwright MCP は 既定でヘッドありです。--headless を明示したときだけヘッドレスで動きます。これは CLI 側（第7手順）と逆なので取り違えやすいところです。
ヘッドレスとヘッドありでは、アイドル時の挙動も違います。--idle-timeout は「ツール呼び出しが完了しないまま指定ミリ秒が経過したらブラウザを閉じる」オプションで、既定値はヘッドレスブラウザで1時間、ヘッドありでは閉じない、0 で無効化、と定義されています。
タイムアウトの既定値を知っておく
不安定なテストを疑う前に、既定値を知っておくと切り分けが速くなります。README の表に書かれている値は次のとおりです。
| オプション | 内容 | 既定値 |
|---|---|---|
| –timeout-action | アクションのタイムアウト | 5000ms |
| –timeout-navigation | ナビゲーションのタイムアウト | 60000ms |
| –timeout-settle | 各アクション後に待つ時間 | 500ms |
| –test-id-attribute | テストIDに使う属性 | data-testid |
--test-id-attribute の既定が data-testid である点は、既存のテストコードと属性名が違うプロジェクトで最初に踏みます。
追加機能はcapsでオプトインする
--caps は追加の機能を有効にするオプションで、指定できる値は vision・pdf・devtools です。ネットワークのモック系ツール（browser_route など）は --caps=network、設定取得の browser_get_config は --caps=config でオプトインする形になっています。必要になるまで有効にしない、が既定の姿勢として妥当です。
4. ページを読む。snapshot・find・screenshotの使い分け
ここからツールの話に入ります。読む側の3つは役割がはっきり分かれています。
browser_snapshotが基本、screenshotは操作に使えない
browser_snapshot は現在のページのアクセシビリティスナップショットを取得するツールで、README の説明は「this is better than screenshot」です。Read-only は true。パラメータには target（スナップショット上の参照またはセレクタ）、filename（応答に載せずファイルへ保存する）、depth（スナップショットツリーの深さを制限する）、boxes（各要素のバウンディングボックスを [box=x,y,width,height] で含める）があります。
一方の browser_take_screenshot の説明には、はっきりと「You can’t perform actions based on the screenshot, use browser_snapshot for actions」と書かれています。スクリーンショットは人間が目視で確認するための出力であって、操作の起点にはしない。この線引きを守らないと、エージェントが画像を根拠に座標を推測しはじめます。
大きなページはfindで刈り込む
ページ全体のスナップショットは、そのまま文脈を食います。browser_find は、現在のページのスナップショットをテキストまたは正規表現で検索し、一致したノードを前後数行の文脈付きで返すツールです。README はこれを「要素とその ref を見つけたいだけなら、スナップショット全体を取るより安い」と説明しています。
browser_find（text: "カートに追加"）
browser_find（regex: "/sign (in|up)/i"）
text と regex はどちらか一方だけを渡します。正規表現は既定で大文字小文字を区別し、スラッシュで囲むとフラグを足せます。
MCP出力の上限を先に知っておく
Claude Code 側には MCP ツール出力の上限があります。出力が 10,000 トークンを超えると警告が出て、既定の上限は 25,000 トークンです。上限は MAX_MCP_OUTPUT_TOKENS 環境変数で引き上げられますが、警告のしきい値は固定です（Anthropic「Connect Claude Code to tools via MCP」（2026年9月18日閲覧））。
export MAX_MCP_OUTPUT_TOKENS=50000
大きな管理画面のスナップショットは、この上限に当たります。上限を上げる前に、browser_find と --depth で刈り込む、--snapshot-mode を none にする、filename でファイルへ逃がす、という順で検討したほうが結果的に安定します。
画像レスポンスの扱いも選べる
--image-responses は画像をクライアントへ返すかどうかを allow・omit・only で切り替えるオプションです。既定は allow。スクリーンショットを取るが LLM の文脈には載せたくない、という運用なら omit が候補になります。
5. 操作する。refの扱いとclick・fill_form・wait_for
操作系のツールは Read-only が false です。ここは権限設計の対象になります。
refはスナップショットから取る
browser_click のパラメータは、element（許可を得るための人間可読な要素説明）、target（スナップショット上の正確な要素参照、または一意なセレクタ）、doubleClick、button、modifiers です。element が「permission を得るための説明」として定義されている点が重要で、Claude Code の許可プロンプトに出るのはこの文字列です。
つまり運用の流れはこうなります。browser_snapshot か browser_find で ref を得る、browser_click に target としてその ref を渡す、browser_wait_for で結果を待つ。座標は一度も出てきません。
フォームはfill_formでまとめる
browser_fill_form は複数のフォームフィールドをまとめて埋めるツールで、パラメータは fields（埋めるフィールドの配列）だけです。1フィールドずつ browser_type を呼ぶより往復が減ります。
選択肢は browser_select_option（values は単一でも複数でも可）、ファイルは browser_file_upload、ダイアログは browser_handle_dialog（accept と promptText）で扱います。
待ちはwait_forに寄せる
browser_wait_for は「テキストが現れる」「テキストが消える」「指定秒数が経つ」の3通りを、text・textGone・time で表現します。textGone があるおかげで、ローディング表示が消えるのを待つ、という書き方ができます。固定の time で待つのは最後の手段にしてください。
run_code_unsafeはRCE相当だと明記されている
browser_run_code_unsafe の説明は明快です。Playwright のコードスニペットを実行するツールで、README はこれを「Unsafe: executes arbitrary JavaScript in the Playwright server process and is RCE-equivalent」と書いています。code に関数を渡すか、filename でファイルから読み込みます。両方渡した場合は code が無視されます。
また、ページ側が登録したツールを呼ぶ browser_webmcp_call には「The tool output is page-provided and untrusted」と明記されています。ページから返る内容は指示ではなくデータとして扱う、という原則がここにも出てきます。
調査系のツールも押さえておく
失敗の原因を追うときは browser_console_messages（--console-level で error・warning・info・debug の粒度を選べる）、browser_network_requests（読み込み以降のリクエストを番号付きで返す）、browser_network_request（番号を指定して、ヘッダーと本文を含む詳細を返す）が使えます。番号でページングする設計になっているので、全リクエストを一度に文脈へ流し込まずに済みます。
6. 権限を切る。mcp__playwright__の許可設計とフック
ここが設計の山場です。Playwright MCP 自体は README に「Playwright MCP is not a security boundary」と書かれています。境界は Claude Code 側で引きます。
ツール名はmcp__server__toolの規則に従う
Claude Code の MCP ツールは mcp__<server>__<tool> という名前で現れます。許可ルールのグロブは、リテラルな mcp__<server>__ 接頭辞の後ろにしか書けません。サーバー名の部分にグロブは使えず、"*" や "mcp__*" のようなアンカーされていない allow グロブは警告付きでスキップされ、何も自動承認しません（Anthropic「Configure Claude Code permissions」（2026年9月18日閲覧））。
ルールの評価順は deny、ask、allow です。最初に一致したものが結果を決め、ルールの具体性は順序を変えません。広い deny は、より狭い allow を貫いて効きます。
読むツールだけallow、操作は ask、危険なものは deny
この規則に沿うと、設定はこうなります。サーバー名を playwright で登録した場合の例です。
{
"permissions": {
"allow": [
"mcp__playwright__browser_snapshot",
"mcp__playwright__browser_find",
"mcp__playwright__browser_console_messages"
],
"ask": [
"mcp__playwright__browser_click",
"mcp__playwright__browser_navigate"
],
"deny": [
"mcp__playwright__browser_run_code_unsafe"
]
}
}
注意点が2つあります。ひとつは、settings ファイルを読み込むとき Claude Code は括弧の付いた mcp__ ルールをスキップすることです。スキップしたルールは対話セッション起動時の invalid-settings ダイアログと claude doctor の出力に出ます。MCP ツールのパラメータで絞りたい場合は、--disallowedTools で deny ルールとして渡します。
もうひとつは、実際のツール名を /mcp パネルで確認してから書くことです。上の例は「mcp__<server>__<tool> の規則」と「README のツール名」を組み合わせたもので、登録時に付けたサーバー名がそのまま真ん中に入ります。
全MCPツールを落とす書き方
deny と ask はツール名の位置にもグロブを取れます。"mcp__*" はすべてのサーバーのすべての MCP ツールに一致し、bare-name のグロブ deny に一致したツールは Claude の文脈から丸ごと取り除かれます。CI のように「MCP は一切使わせない」経路では、この形が確実です。
フックで操作の記録を残す
フックのマッチャーでも同じ命名規則が使えますが、書き方が少し違います。mcp__playwright__.* のように .* を付けないと一致しません。mcp__playwright のように完全一致文字だけのマッチャーは文字列比較として扱われ、どのツールにも一致しない、と公式ドキュメントが明記しています（Anthropic「Hooks reference」（2026年9月18日閲覧））。
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__playwright__.*",
"hooks": [{ "type": "command", "command": "./scripts/log-browser-action.sh" }]
}
]
}
}
MCP ツールは PreToolUse・PostToolUse・PostToolUseFailure・PermissionRequest・PermissionDenied の各イベントに、通常のツールと同じように現れます。なお、フック入力の mcp_server オブジェクト（サーバーの name と source）は Claude Code v2.1.274 以降で利用できます。信頼の判断は name や mcp__<server>__ 接頭辞ではなく source を基準にする、というのが公式の指示です。
権限ルールの一般論はClaude Code権限設計ガイド、フックの書き方はClaude Code Hooks実践ガイドで扱っています。
ネットワークの許可リストは境界ではない
--allowed-origins と --blocked-origins はセミコロン区切りでオリジンを指定するオプションですが、README は両方について「does not serve as a security boundary and does not affect redirects」と明記しています。ブロックリストは許可リストより先に評価されます。
ファイルアクセスは既定で制限されています。ワークスペースルート（ルートが設定されていなければ作業ディレクトリ）の外にあるファイルへのアクセスと file:// URL への遷移はブロックされ、--allow-unrestricted-file-access を付けたときだけ解放されます。このフラグは付けない前提で設計するのが安全です。実行環境そのものを隔離したい場合は、Claude CodeサンドボックスやDev Container側の記事が前提になります。
7. MCPかCLIとSkillsか。トークン効率で選び分ける
見落としやすいのですが、Microsoft は同じ README の冒頭で「コーディングエージェントを使っているなら CLI と SKILLS のほうが向いているかもしれない」と自ら書いています。
公式が示している判断軸
README の比較はこうです。CLI は、ツールスキーマや冗長なアクセシビリティツリーを文脈へ読み込ませずに済むぶんトークン効率が良く、大きなコードベースやテストと並行して動くエージェントに向く。MCP は、永続的な状態・豊富な内省・ページ構造への反復的な推論から利益を得る用途、たとえば探索的な自動化、自己修復するテスト、長時間動く自律ワークフローで、文脈コストを払ってでもブラウザの文脈を維持したい場合に向く（Microsoft「playwright-cli」README（2026年9月18日閲覧））。
CLIを選ぶ場合の導入手順
CLI 側は npm のグローバルインストールと、Skills のインストールコマンドが用意されています。
npm install -g @playwright/cli@latest
playwright-cli install --skills
README は「Claude Code、GitHub Copilot などはローカルにインストールされた skills を使う」と書いています。Skills を入れない運用も可能で、その場合はエージェントが playwright-cli --help を自分で読んで使い方を把握します。
操作の粒度は MCP のツールとほぼ対応しています。playwright-cli snapshot で ref を取り、playwright-cli click e15 のように参照で操作し、playwright-cli find "カートに追加" で刈り込む。CSS セレクタや getByRole('button', { name: 'Submit' }) のような Playwright ロケータも渡せます。
CLI側の既定はheadless、セッションはメモリ上
ここが MCP と逆です。Playwright CLI は既定で headless で、ブラウザを見たいときは open に --headed を渡します。プロファイルは既定でメモリ上に保持され、--persistent を付けるとディスクへ保存されます。ヘッドレスのセッションはコマンドが1時間来ないと自分で終了し、ヘッドありのブラウザは開いたままです。
セッションは -s= で名前を付けて並列運用でき、PLAYWRIGHT_CLI_SESSION 環境変数を使えばエージェント側にセッションを固定できます。
PLAYWRIGHT_CLI_SESSION=todo-app claude .
playwright-cli list でセッション一覧、playwright-cli close-all で全ブラウザを閉じる、playwright-cli show で全セッションのライブ画面を見るダッシュボードが開きます。エージェントが裏でブラウザを触っているときに様子を見たい、という場面で効きます。
CLIを使うならBashルールの書き方に注意する
CLI に寄せるとき、Claude Code 側の許可は MCP ルールではなく Bash ルールになります。ここで踏みやすい落とし穴が npx です。Claude Code は一部のラッパー（timeout・time・nice・nohup・stdbuf など）を剥がしてからルールを照合しますが、npx や docker exec のような開発環境ランナーはその一覧に入っていません。Bash(devbox run *) のようなルールは run の後ろに来るものすべてに一致してしまう、と公式ドキュメントが例示しています（Anthropic「Configure Claude Code permissions」（2026年9月18日閲覧））。
対策は、ランナーと内側のコマンドの両方を含む具体的なルールを1つずつ書くことです。グローバルインストールした playwright-cli を直接呼ぶ形に統一しておくと、ルールが素直になります。
{
"permissions": {
"allow": ["Bash(playwright-cli snapshot *)", "Bash(playwright-cli find *)"],
"ask": ["Bash(playwright-cli click *)", "Bash(playwright-cli goto *)"]
}
}
なお、Bash ルールは Claude が書いたコマンド文字列に対して照合されるもので、同じプログラムを別の形（/usr/bin/... やシェル経由）で呼ばれた場合は一致しません。公式ドキュメントも「Bash の deny/ask ルールはプログラムに対するセキュリティ境界ではない」と明記しています。強制力が必要なら、実行環境側で制限してください。
併用するならサーバーは1つに絞る
MCP と CLI を両方入れると、同じワークスペースのプロファイルを取り合う可能性があります。第3手順で触れたとおり、永続プロファイルは同時に1つのブラウザからしか使えません。どちらかに寄せるか、少なくとも一方を --isolated 側へ逃がしてください。
セッション単位で MCP 設定を固定したい場合は、--strict-mcp-config と --mcp-config の組み合わせが使えます。--strict-mcp-config は --mcp-config で渡したサーバーだけを使い、他の MCP 設定を無視します。プロジェクトスコープのサーバーに対する承認待ちをスキップする挙動は Claude Code v2.1.246 以降です。
想定モデル事例：ログイン後の申込フォームを回帰チェックに載せる
ここからは実在の導入事例ではなく、上記の仕様だけから組み立てた想定モデル事例です。数値目標や成果は書きません。
想定する場面
社内向けの申込フォームがあり、ログイン後にしか到達できない。手動の確認が毎リリース発生していて、E2E テストは書かれていない。Claude Code は既に日常的に使っている、という状況を想定します。
4段階への置き換え
- 状態を用意する：Playwright 本体の手順でログイン済みのストレージ状態を作り、
--isolated --storage-stateで読み込ませる。認証情報は--secretsのファイルへ置く - 画面を読む：
browser_navigateで申込フォームへ移動し、browser_findでフォーム要素のrefだけを取る。browser_snapshotを全体に対して撮らない - 操作して待つ：
browser_fill_formで必要項目をまとめて埋め、browser_clickで送信し、browser_wait_forのtextで完了表示を待つ - 証跡を残す：
browser_take_screenshotをfilename付きで保存し、失敗時だけbrowser_console_messagesとbrowser_network_requestsを取る
先に決めておくこと
- 許可は「読むツールは allow、操作するツールは ask、
browser_run_code_unsafeは deny」から始める - テスト用アカウント以外の資格情報をストレージ状態に入れない
- 本番環境へは向けない。
--blocked-originsは境界ではないので、環境の分離そのもので担保する - 生成された手順は最終的に Playwright のテストコードへ落とす。エージェントの手順書のままにしない
ここまでの流れは、既存のQA・テスト自動化の実践ガイドとテスト自動生成・TDDの手順に、ブラウザ操作の層を1枚足したものとして読めます。
よくある質問
Q. Claude Code への登録は1行だけで済みますか。
README の Claude Code 向け手順は claude mcp add playwright npx @playwright/mcp@latest の1行です。ただし --headless や --isolated のようなサーバー側のオプションを渡す場合は、Claude Code 自身のオプションと区切るために -- が必要になります。公式ドキュメントは「-- を書かないと Claude Code がサーバーのフラグを自分のオプションとして解釈しようとする」と説明しています。
Q. ヘッドレスで動かすには何を渡しますか。
Playwright MCP は既定でヘッドありなので、--headless を明示します。逆に Playwright CLI は既定で headless で、見たいときに open --headed を渡します。MCP と CLI で既定が逆である点に注意してください。
Q. スナップショットが大きすぎて文脈を圧迫します。
まず browser_find で必要なノードだけを取り、browser_snapshot を使う場合は depth で深さを制限するか filename でファイルへ逃がします。それでも足りない場合に、MCP 出力の上限（既定 25,000 トークン、警告は 10,000 トークン）を MAX_MCP_OUTPUT_TOKENS で引き上げます。警告のしきい値は固定です。
Q. スクリーンショットを見て操作させることはできますか。
できません。browser_take_screenshot の説明には「スクリーンショットに基づいて操作はできない、操作には browser_snapshot を使う」と明記されています。スクリーンショットは人間が確認するための出力として扱ってください。
Q. どのツールを禁止しておくべきですか。
まず browser_run_code_unsafe です。README がこれを「RCE 相当」と明記しています。ページ側が登録したツールを呼ぶ browser_webmcp_call も、出力がページ由来で信頼できないと明記されているので、必要になるまで有効にしない扱いが無難です。MCP ツールを丸ごと落とすなら deny に "mcp__*" を書きます。
Q. 複数のセッションで同時に使えますか。
永続プロファイルは一度に1つのブラウザインスタンスからしか使えません。同じワークスペースを共有する複数の MCP クライアントは衝突します。並列で動かすなら、追加のクライアントを --isolated で起動するか、別の --user-data-dir を指定してください。
Q. MCP と CLI、どちらを選ぶべきですか。
Microsoft 自身の説明では、コーディングエージェント向けにはトークン効率の面で CLI と Skills が向き、探索的な自動化・自己修復するテスト・長時間動く自律ワークフローのようにブラウザの文脈を維持したい用途では MCP が向く、とされています。まず CLI を試し、ブラウザ状態を保ったまま反復させたい場面が出てきたら MCP を足す、という順序が現実的です。
運営元 Uravation よりこの事例を自社の業務で試す場合のテーマ選定・評価・本番移行の確認項目を、無料のチェックリストにまとめています。 Claude Code業務自動化PoCチェックリストを受け取る（無料）
参考・出典
- Microsoft「Playwright MCP」README（2026年9月18日閲覧）
- Microsoft「playwright-cli」README（2026年9月18日閲覧）
- Anthropic「Connect Claude Code to tools via MCP」（2026年9月18日閲覧）
- Anthropic「Configure Claude Code permissions」（2026年9月18日閲覧）
- Anthropic「Hooks reference」（2026年9月18日閲覧）
- Anthropic「CLI reference」（2026年9月18日閲覧）
- Playwright「Authentication」（2026年9月18日閲覧）
- Model Context Protocol「Security Best Practices」（2026年9月18日閲覧）
