Playwright E2E MCP

playwright-e2e-mcp

AI エージェントのためのテストドクター。
Playwright テストが失敗したら、AI が原因を突き止め、修正し、修正が機能することを証明します。

⭐ デバッグにかかる時間を節約できたら、スターを付けて、ほかの Playwright ユーザーにも見つけてもらいましょう。

はじめに · ツール · ツールリファレンス · GitHub Action · 設定 · 変更履歴 · コントリビューション

MCP サーバーであり、エージェントスキルでもあるこのツールは、AI アシスタント （Claude、Cursor、VS Code Copilot、Gemini、Codex）に、テストランナー、 失敗の原因を突き止めるツール、そして修正後に自分で確認する修正ツールを含む、Playwright のフルツールキットを提供します。ほかのツールでは、AI がブラウザーを操作できます。このツールなら、テストスイートを成功した状態に保てます。

❌ 導入しない場合 / ✅ 導入した場合

導入しない場合、エージェントは Timeout 5000ms exceeded waiting for getByTestId('checkout') を確認して、新しいセレクターを推測し、テストを編集して、うまくいくことを期待します。あるいは、実際のバグを残したままテストを「修正」します。

導入した場合、エージェントはテスト失敗時のページを読み取り、そのページ上で一意であると検証されたロケーターに置き換え、テストを再実行し、成功した場合にのみ編集を維持します。ボタンが本当になくなっている場合は、アプリのバグだと知らせます。

run-test ──────┐
load-report ───┴─▶ get-failure ──▶ suggest-fix (apply + re-run) ──▶ green
 (CI job report)        │                 └─ refuses when the element is really gone (app bug)
                        └─ DOM at failure, failed requests, console errors
every run ──▶ analyze-history (flaky / broken / slow / which commit broke it)
test code ──▶ audit-tests (flake risks, ranked by history, verified rewrites)
red at HEAD ─▶ bisect-failure (runs it across git history, names the breaking commit)

主な機能

• 修正は推測ではなく、検証済みです。 修正を採用する前に毎回テストを再実行し、テストがまだ失敗する場合は元に戻します。
• 誠実です。 テストを通すために、実際のバグを覆い隠すことはありません。
• CI の失敗にも対応します。 CI ジョブのレポートとトレースを読み込み、同じ診断と修正を得られます。
• 根拠のある不安定性の診断。 不安定なテストの名前、原因が競合状態、共有状態、テスト順序のどれなのか、再現用のシードを示します。
• 軽量です。 core ツールセットでは、壊れたロケーターの特定と修正にかかったトークン数は約 5,500 で、Playwright MCP とシェルの組み合わせでは約 7,900 でした。19 個すべてのツールを読み込むと、各リクエストに定義が約 16k トークン追加されるため、使用するプロファイルだけを読み込んでください（ベンチマーク）。
• 無料のオープンソースです。 MIT ライセンスで、アカウント、API キー、テレメトリーは不要です。すべてのツールが無料です。任意の有料 Pro プランでは、ホスト型 CI 履歴が追加されます。

🚀 この MCP だけができること

ほとんどのテスト用 MCP では、AI がブラウザーを操作できます。Microsoft の Playwright MCP、Chrome DevTools MCP、ExecuteAutomation の mcp-playwright、Selenium MCP などがあり、ページ上の操作には最適です。しかし、2026 年 10 月時点で、以下のことができるものはありません。この MCP ならできます。

ブラウザー MCP を置き換えるのではなく、併用できます。ブラウザー MCP がページを操作し、この MCP がテストスイートを成功した状態に保ちます。

質問できること

要件

• Node.js 22 以降
• @playwright/test を使用し、ブラウザーをインストール済みのプロジェクト（npx playwright install chromium）
• Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Codex、Gemini CLI、またはその他の MCP クライアント

はじめに

最速の方法： プロジェクトのルートで次を実行します。見つかったすべてのクライアント設定（Claude Code、Cursor、VS Code、Gemini CLI、Codex）にサーバーを追加し、エージェントスキルをインストールします。他のサーバーには手を加えません。

npx -y playwright-e2e-mcp init            # --client all | cursor,vscode … · --dry-run
npx -y playwright-e2e-mcp doctor          # checks Node, Playwright, browsers and client setup

エージェントにインストールを任せる方法もあります。 次の内容を任意のコーディングエージェントに貼り付けてください。

https://raw.githubusercontent.com/xsignon-secure/E2E/main/llms-install.md の手順に従って、playwright-e2e-mcp サーバーとスキルをインストールしてください。

標準設定は、ほとんどのクライアントで使用できます。

{
  "mcpServers": {
    "playwright-e2e": {
      "command": "npx",
      "args": ["-y", "playwright-e2e-mcp"]
    }
  }
}

サーバーは、作業ディレクトリをプロジェクトのルートとして使用します。クライアントが別の場所（ホームディレクトリなど）でサーバーを起動する場合は、"env": { "PW_MCP_PROJECT_ROOT": "/path/to/your/project" } を追加してください。

/plugin marketplace add xsignon-secure/E2E
/plugin install playwright-e2e-mcp@xsignon-secure

claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp

code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","playwright-e2e-mcp"]}'

codex mcp add playwright-e2e -- npx -y playwright-e2e-mcp

[mcp_servers.playwright-e2e]
command = "npx"
args = ["-y", "playwright-e2e-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 600

gemini extensions install https://github.com/xsignon-secure/E2E

最初のプロンプト

クライアントを再起動してから、次のように依頼します。

Run my Playwright tests and fix whatever fails.

エージェントはテストスイートを実行し、失敗内容を読み取り、再実行して確認した修正案を提示するはずです。自分のテストを使わずに セットアップを確認するには、このリポジトリのexamples/sample-test.spec.tsを実行するよう依頼してください。

0.7 の新機能

• 一度ログインすれば安全に利用できます： save-login は、環境変数から読み込んだシークレットを使ってサインインし（2FA コードを含む）、セッションを確認して storageState ファイルとして保存します。セッションが有効な間は再利用します。
• 修正ガード： check-test-change と playwright-e2e-mcp guard は、テストのチェックを減らすことで通過する「修正」（アサーションの削除、テストのスキップ、.only）をブロックします。
• 不安定なテストの隔離： quarantine は、既知の不安定なテストが一定期間ビルドを失敗させないようにします。オーナーと理由を指定でき、その間もテストの実行とレポートは継続されます。

0.6 の新機能

• テストを壊したコミットを特定： bisect-failure は一時的なワークツリーで Git の履歴をまたいでテストを実行し、最初に失敗したコミット、その変更内容、およびそこでの失敗内容を報告します。
• 不安定化リスクの監査： audit-tests は、実際の不安定さに基づいて順位付けしながら、固定時間の待機、1 回限りのアサーション、await の不足、壊れやすいセレクターを検出し、安全な書き換えを適用して検証実行を行います。
• プルリクエストでワンクリック修正： GitHub Action が CI で各修正を検証し、提案された変更として投稿します。
• doctor： npx playwright-e2e-mcp doctor は Node、Playwright、ブラウザー、クライアントの設定を確認します。
• 構造化された結果： すべてのツールは Markdown とともに JSON を返し、出力スキーマを備えています。
• スマートフォン、タブレット、Chrome、Edge： すべてのページツールで device プリセットと channel を利用でき、Docker イメージは ghcr.io で公開されています。
• Node 22 以降が必須になりました。また、ホストされたエンドポイントではキーの推測が制限されています。

すべてのリリースノート

ツール

すべての引数と出力例は**ツールリファレンス**に記載されています。すべてのツールには MCP ツールアノテーション（readOnlyHint、destructiveHint、…）が付いているため、クライアントは適切な安全性確認の プロンプトを表示できます。

修正ループだけが必要ですか？ --tools=core（または PW_MCP_TOOLS=core）を指定すると、7 つのツールが公開され、 ツール定義のコンテキストを約 4 分の 1 に削減できます。その他のプロファイル：triage、inspect、author。

CI：GitHub Action と ci コマンド

同じ診断をエージェントなしで実行できます。playwright-e2e-mcp ci は テストスイートを実行し（不安定なテストを失敗ではなく不安定として報告するため、一度自動再試行します）、 失敗に対する suggest-fix の差分案と不安定性の判定を任意で作成し、Markdown レポートを 1 つ、 標準出力、--output、および GITHUB_STEP_SUMMARY が設定されている場合は GitHub ジョブの サマリーに出力します。終了コードは、成功が 0、テスト失敗が 1、実行自体の失敗が 2 です。

npx -y playwright-e2e-mcp ci --flaky-runs 3 --suggest 2 --output report.md
npx -y playwright-e2e-mcp ci --help

GitHub Action として使用すると、レポートをジョブのサマリーに追加し、実行が失敗した場合は PR コメントを 1 つ最新の状態に保ちます。プルリクエストでは、失敗した各テストを推奨修正で再実行し、 成功した修正を失敗行への変更提案として投稿します。レビュー担当者は提案をコミットボタンで適用できます （PR で変更された行のみが対象で、それ以外はレポートに残ります）。

permissions:
  contents: read
  pull-requests: write   # for the PR comment and the suggested fixes
steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
    with: { node-version: 24 }
  - run: npm ci && npx playwright install --with-deps chromium
  - uses: xsignon-secure/[email protected]
    with:
      flaky-runs: 3      # 0 skips the flaky verdict
      suggest: 2         # suggest-fix diffs for the first 2 failures
      # args: --browser chromium tests/checkout

アーティファクトのアップロードと、guard: true および Pro Cloud のコメントアウトされたオプションを含む、すぐにコピーして使える完全なワークフローが examples/github-actions/playwright-e2e.yml にあります。

入力：project-root、args、flaky-runs、suggest、comment、review、 verify-fixes、guard、pro-key、pro-url、fail-on-failure、version、github-token。出力：exit-code、 report、guard。

隔離されたテスト（playwright-quarantine.json。詳細は quarantine を参照）もここで考慮されます。失敗したテストがすべて隔離され、期限切れでない場合、ci は終了コード 0 で終了し、レポートにそれらのテストを記載します。

CI での Heal guard。 guard: true を指定すると、まず PR で変更されたテストをベースブランチと照合し、 確認範囲を狭めることでテストを成功させていた場合はジョブを失敗させます。Action を使わない場合：

npx -y playwright-e2e-mcp guard --base origin/main   # exit 1 on BLOCK; --strict fails on warnings too

設定

{"time":"2026-10-07T08:00:00.000Z","level":"info","message":"server ready","name":"playwright-e2e-mcp"}

ベンチマーク

bench/token-benchmark.mjs は、ストアフロントページのチェックアウトボタンのテスト ID を壊し、2 つの方法で修正します。このサーバーを使う方法（run-test → suggest-fix → 適用）と、Playwright MCP とシェルを使う方法（playwright test、browser_navigate + browser_snapshot、編集、再実行）です。最新の結果（全出力）：

トークン数は文字数 ÷ 4 です。作業そのもの（実行、診断、修正、検証）に必要なトークン数は、このサーバーでは約 700 ですが、Playwright MCP では約 2,600 です。ただし、ツール定義は各リクエストで送信されます。19 個すべてのツールを読み込むと、この削減分を上回るため、失敗するテストの修正だけを行う場合は PW_MCP_TOOLS=core（または別のプロファイル）を設定してください。Playwright MCP の方法は下限値です。エージェントがスナップショットから最初の試行で適切なロケーターを選ぶことを前提としており、このサーバーはここでそれを実行します。2026-10-28 に 0.7.0 と Playwright 1.64.1 で実行しました。npm run build && node bench/token-benchmark.mjs で再実行できます。

デモ

バンドルされている examples/sample-test.spec.ts に対して、npx -y playwright-e2e-mcp が stdio 経由で提供した、実際の run-test 呼び出し（実際の出力、編集なし）：

無料のオープンソース

• MIT ライセンスです。 使用、変更、商用利用が可能で、料金はかからず、制限される機能もありません。オプションの Pro プランでは、ホスト型サービス（複数のマシンにまたがる CI 実行履歴）が追加されますが、ツールは追加されません。ここに記載されている機能に Pro プランは必要ありません。
• アカウント、API キー、登録は不要です。 npx -y playwright-e2e-mcp init だけでセットアップできます。
• テレメトリはありません。 外部への通信は行われません。Pro キーを設定してアップロードしない限り、テスト、トレース、実行履歴はお使いのマシンに保持されます。
• 依存関係はすべて無料です： MCP SDK（Apache-2.0）、zod（MIT）、axe-core（MPL-2.0）、およびプロジェクトにすでに含まれている Playwright（Apache-2.0）。
• セルフホストも無料です。 HTTP ブリッジは無料の Vercel アカウントにデプロイできます（ホスト型エンドポイントを参照）。

対応していないこと： 探索的なブラウジングセッションを段階的に操作するものではなく、VS Code 内で Playwright 独自の Test Agents に置き換わるものでもありません。対話的なブラウジングには Playwright MCP を、テストスイートの実行、診断、修正にはこのサーバーを使用してください。両者は併用できます。

その他のドキュメント

• ツールリファレンス：各引数、出力例、対応するエッジケース
• ホスト型エンドポイント：ChatGPT および claude.ai コネクター向けの HTTP ブリッジ
• セキュリティ：セキュリティモデルと脆弱性の報告方法
• 開発：ビルド、テスト、Docker、署名、リリース
• コントリビューション · 行動規範

ライセンス

MIT。このツールでデバッグにかかる時間を節約できたら、リポジトリに ⭐ を付けていただけると、ほかの Playwright ユーザーにも見つけてもらいやすくなります。