Playwright MCPの接続手順｜ログイン画面はどこまで動くか

Playwright MCPは、スクリーンショットではなくアクセシビリティツリーを介してブラウザを操作するMCPサーバーです。本記事はWEBMARKSの自環境への接続実行ではなく、公式リポジトリとドキュメントの記述確認（2026-07-29確認）に基づきます。接続手順とログイン画面・動的サイトでの動作範囲、ヘッドレス実行時のつまずきポイントを設計論として整理します。

01結論：Playwright MCPで自動操作できる範囲とできない範囲

WEBMARKSは本記事の執筆時点で、Playwright MCPを自社の本番業務へ接続していません。ここから先は、公式リポジトリと公式ドキュメントの記述に基づく設計論として書きます。実際に使ってどうだったかという体感は書きません。

結論を先に3点でまとめます。

• 接続はローカルプロセス（stdio）で完結し、Claude CodeならPlaywright MCPをclaude mcp addのコマンド1本で登録できます
• ログイン画面のフォーム操作そのものは、他の画面と同じ手順で動きます。ただし「認証済み状態を外から渡す」設計に沿う場合に限られ、2要素認証やCAPTCHAへの対応はREADMEに記述がありません
• ヘッドレス実行では、既定の永続プロファイルやDocker実装の対応範囲が変わり、事前確認が要ります

Playwright MCPは、Microsoftが公開するMCPサーバーです（出典: 公式リポジトリ microsoft/playwright-mcp）。土台になっているのは、E2Eテスト用フレームワークPlaywrightのブラウザ制御機能です。

大きな設計判断は、操作の根拠をスクリーンショットではなくアクセシビリティツリーに置いたことです。README自体が「LLMフレンドリーで、視覚モデルを必要とせず、構造化データのみで動作する」と説明しています（出典: 公式リポジトリ）。

02Playwrightの接続手順｜3ステップで有効化する

Claude Codeへ接続する場合、公式ドキュメントが示すstdio型MCPサーバーの追加構文に沿います（出典: Claude Code公式MCPドキュメント）。

# 1. サーバーを登録する（自分専用のlocalスコープが既定）
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

# 2. 接続状態を確認する
claude mcp list

チームで共有する場合は--scope projectを付け、.mcp.jsonへ書き出します。この考え方は『MCPの選び方｜権限と提供元で見る判断軸5つ』で扱ったscope設計と同じです。project scopeのサーバーは、Claude Codeが起動時に「承認待ち」として一覧に出します。実行者ごとに1回は個別承認が要ります（出典: Claude Code公式MCPドキュメント）。

npxはパッケージを都度取得するため、初回実行時にネットワークアクセスが発生します。オフライン環境や社内プロキシ配下では、--proxy-server・--proxy-bypassを事前に設定します（出典: 公式リポジトリ）。

03ログイン画面はPlaywrightでどこまで動くか｜4つの認証パターン

フォーム操作そのものに、ログイン画面特有の制限はありません。browser_fill_formやbrowser_typeは、ログインフォームも他のフォームと同じ手順で入力します。問題になるのは「その先に認証済みの状態をどう維持・再利用するか」です。

公式READMEは、認証状態の扱いを4パターンで説明しています（出典: 公式リポジトリ）。

Playwright本体のドキュメントも、認証状態の保存ファイルについて明確に警告しています。「なりすましに使われかねない機微なクッキーやヘッダーを含む可能性がある」という文言です。そのうえで、リポジトリへのコミットを強く戒めています（出典: Playwright公式ドキュメント）。

WEBMARKSの社内ルールは、資料に記載されたIDとパスワードでのログインを禁止し、保存も禁止しています。この考え方は、Playwright MCPの認証状態ファイルにもそのまま当てはまります。状態ファイルはID・パスワードそのものではありませんが、それを使えば本人としてログインし直せる点で、実質的に機微な認証情報と同じ扱いが要ります。

READMEには、2要素認証やCAPTCHAをPlaywright MCPがどう扱うかの記述がありません。一般に、ヘッドレスブラウザは自動化ツールとして検知されやすく、ボット判定の対象になりやすいことが知られています。ただしPlaywright MCP自身が検知回避の機能を持つとは、公式文書のどこにも書かれていません。

04動的サイトでPlaywrightがつまずく場面｜レンダリング待ちと検知

JavaScriptで内容が後から差し込まれる動的サイトでも、Playwrightのアクセシビリティツリーを使う設計自体は有利に働きます。DOMの更新に追随するため、決まった座標の画像を待つスクリーンショット依存の自動化より、要素の出現を検知しやすい設計です。

とはいえ、待つ責任は呼び出す側に残ります。browser_wait_forはテキストの出現または時間経過を待つツールです。browser_snapshotは呼び出した瞬間の状態しか返しません（出典: 公式リポジトリ）。レンダリングの完了を待たずにbrowser_snapshotを呼べば、まだ描画されていない要素はそのまま欠落します。

デバッグに使えるツールも用意されています。browser_console_messagesはコンソールログを返します。browser_network_requestsは読み込んだページのネットワークリクエスト一覧を返します（出典: 公式リポジトリ）。想定した要素が取得できないとき、まずこの2つで描画やAPI呼び出しが終わっているかを切り分けられます。

iframe内やShadow DOM内の要素を、アクセシビリティスナップショットがどこまで拾うかについては、公式READMEに直接の記述がありません。ブラウザ自体のアクセシビリティツリー生成に依存する部分のため、対象サイトごとに確認が要る領域として、ここでは断定を避けます。

ネットワークリクエストのモック機能（browser_route）は既定では無効です。--caps=networkを指定したときだけ使えます（出典: 公式リポジトリ）。動的サイトを決まった条件で再現性高く扱いたい場合、この機能の追加検証が視野に入ります。

05権限を絞る接続設計｜Playwrightのcapabilityとdenyリスト

公式READMEは、Playwright MCP自体について「セキュリティの境界ではない」と明記しています（出典: 公式リポジトリ）。ファイルアクセス制限のオプションについても「LLMがワークスペース外へさまよい出ることを防ぐ利便性の防御であり、安全な境界ではない」と説明されています。

とりわけ注意が要るのがPlaywright側のコード実行系ツールです。browser_run_code_unsafeは、Playwrightサーバーのプロセス内で任意のJavaScriptを実行します。README自身がこの機能を「RCE相当」と表現しています（出典: 公式リポジトリ）。

Claude Code側は、MCPサーバーのツールをmcp__サーバー名__ツール名という形式で権限ルールの対象にできます。『Claude Codeの権限設定｜allow・ask・denyの配分と設定例』で扱った枠組みがそのまま使え、危険度の高いツールだけを狙ってdenyへ回せます。

{
  "permissions": {
    "deny": [
      "mcp__playwright__browser_run_code_unsafe",
      "mcp__playwright__browser_file_upload"
    ],
    "ask": [
      "mcp__playwright__browser_navigate"
    ]
  }
}

Playwrightの機能は既定ですべて開いているわけではありません。--capsのオプトイン方式で有効化する分類は7つあります（出典: 公式リポジトリ）。

• ネットワーク：browser_routeによるリクエストのモック
• ストレージ：クッキー・localStorage・sessionStorageの取得や書き換え
• DevTools：トレース記録・録画・要素ハイライト
• 座標クリック：vision指定によるマウス座標操作
• PDF生成：browser_pdf_save
• テストアサーション：browser_verify_element_visibleなどの検証系
• 設定確認：browser_get_configで最終的な設定値を取得

使わない分類を有効化しないことも、Playwright MCPの権限を絞る接続設計の一部です。

機密情報の扱いをさらに絞りたい場合、--secretsオプションでdotenv形式の秘密情報ファイルを指定できます（出典: 公式リポジトリ）。機能自体は用意されていますが、機密の保存場所を社内のどこに置くかは、社内ルールに沿って別途決める必要があります。隔離設計の考え方は『機密をAIエージェントに渡さない｜gitignoreとフォルダ構成』で扱っています。

06Playwright MCPで実際につまずく3つのヘッドレス関連ポイント

WEBMARKSはPlaywright MCPを未接続のため、ここは公式ドキュメントの仕様から読み取れる、事前に押さえておくべき3点です。

1. 既定の永続プロファイルは、ヘッドあり実行が前提になっている。 READMEは「すべてのログイン情報が保存される永続プロファイル、セッション間で削除可能」と説明しますが、これは--isolatedを付けない場合の話です。分離モードでは「セッションごとに独立したプロファイルを使い、閉じるとストレージは失われる」と明記されています（出典: 公式リポジトリ）。ヘッドレスCIで毎回まっさらな環境から動かしたいなら分離モードと相性が良く、前回のログイン状態を引き継ぎたいなら不向きです。

2. Docker実行はヘッドレスChromium限定。 公式リポジトリは「Dockerによる実装は、現時点でヘッドレスChromiumのみサポートする」と明記しています（出典: 公式リポジトリ）。FirefoxやWebKitでの検証をヘッドレスCIに組み込みたい場合、Docker以外の実行方式を検討する必要があります。

3. stdio接続は、切れても自動で再接続しない。 Claude Code公式ドキュメントによると、HTTP・SSEサーバーは切断時に最大5回まで自動再接続します。stdioサーバーはローカルプロセスのため、自動では再接続されないと明記されています（出典: Claude Code公式MCPドキュメント）。npx起動のPlaywright MCPは既定でstdio接続のため、プロセスが落ちても次の呼び出しまで気づけないことがあります。

07Playwright MCPを導入する前のチェックリスト

• Playwright MCPの登録コマンド（claude mcp add --transport stdio）を確認した
• local・project・userのどのスコープで登録するかを決めた
• --capsで有効化する分類を、使う機能だけに絞った
• browser_run_code_unsafeなど危険度の高いツールをdenyリストへ入れた
• ログイン状態の再利用方法（永続プロファイル・storage-state・user-data-dir・拡張機能）を1つ選んだ
• storage-stateファイルをGit管理・共有フォルダから除外した
• ヘッドレスで動かす場合、--isolatedの有無とDockerの対応ブラウザを確認した
• stdio接続が切れても自動再接続しないことを前提に、失敗時の検知手段を用意した

08FAQ