E2E MCP Server

playwright-e2e-mcp

An MCP server that lets AI agents run, debug, and inspect Playwright end-to-end tests — with structured results, actionable failure diagnostics, and live DOM inspection.

run-test ──▶ get-failure ──▶ inspect-page ──▶ validate-selector ──▶ fix ──▶ re-run
   ▲                                                                    │
   └──────────────────────── list-tests ◀────────────────────────────────┘

Instead of handing an agent raw Playwright output, this server turns every run into machinable results: pass/fail stats, per-failure messages with file:line, a failure kind (assertion, timeout, browser crash, syntax error, dead dev server, full disk…), and a concrete "how to fix" hint. When a test fails because a selector no longer matches, the agent can open the live page in a headless browser, see the real DOM with unique CSS selectors, and validate the replacement selector before re-running.

Install

Works with Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Freebuff and every other MCP client — pick whichever route fits:

Details and per-client config: Installation · MCP client configuration.

---

Tools

run-test

Flakiness handling: by default the server injects --retries=1 (unless the config already sets retries), so a test that passes on the retry is reported as flaky, not failed. Traces are captured automatically (--trace=retain-on-failure) so get-failure can show the DOM at the moment of failure.

Example result:

## Playwright run — ❌ FAILED

**Command:** `playwright test --config playwright.config.ts tests/checkout.spec.ts --reporter=json`
**duration 4.2s · exit 1 · config `playwright.config.ts`**

| passed | failed | flaky | skipped | duration |
| ---: | ---: | ---: | ---: | ---: |
| 0 | 1 | 0 | 0 | 1.1s |

### ❌ 1 failing test(s)

### 1 of 1. checkout.spec.ts › pays with card
**File:** `checkout.spec.ts:5`  |  **failed · server-unreachable**

### ⚠️ SERVER_NOT_RUNNING
Your app (dev server) does not appear to be reachable. Start it in another terminal
(e.g. npm run dev / npm start), keep it running, then retry — or configure `webServer`
in playwright.config.* so Playwright starts it automatically.

get-failure

Returns the message/code frame, expected vs actual, stack, failure kind with a diagnosis, the test's console output, the DOM snapshot from the Playwright trace (plus the failed action, its selector, and the action log leading up to it), the network requests that failed (4xx/5xx, dead endpoints, no-response — with method, URL, status and resource type), the console errors/warnings the page logged before the failure, and numbered next steps (re-run this single test by file:line, headed/debug mode, validate-selector when the message mentions a locator, …).

inspect-page

Returns each element's unique CSS selector, tag, visibility, bounding box, text and attributes, plus captured console messages (errors first).

list-tests

Uses playwright test --list when Playwright works, and falls back to a source scan (keeping the reason) when the install or a spec file is broken.

validate-selector

Verdicts: ✅ VALID — N matches (with a sample of matches), ✅ VALID — 0 matches (with debugging advice), ❌ INVALID (parse error + fix), or a warning when the input uses a Playwright-only engine (text=, xpath=, >>, :has-text()), which is not plain CSS.

generate-e2e-test

Reads the agent's recent changes (git status, falling back to git diff HEAD~1, then recent mtimes), extracts the locators those files actually declare (data-testid, getByRole, aria-label, placeholder, id, name, element text), ranks verified-live selectors first, writes a spec built from them, and reports each selector with its source file:line.

compare-visual-state

The first call saves a baseline under .pw-mcp/visual/ (add that to .gitignore, or commit it for CI comparisons). Later calls report changed-pixel counts, merged regions ((x, y) 120×40 — 1,200 px), the average color shift ("blue → red"), and write a red-highlighted diff image for review.

diagnose-flaky

Every run executes with --retries=0 and auto-retry disabled, so each result is honest evidence. The response contains a per-run table (status, duration, first failure), the count of distinct normalized error signatures, and one of:

• ❌ CONSISTENTLY FAILING — failed every run (same error → reproducible bug, different errors → still broken, just noisy). Fix it; it is not flaky.
• ⚠️ FLAKY — some runs passed. Includes N of M counts and whether the failures share one signature (real intermittent bug) or vary (timing/environment instability).
• ✅ NOT REPRODUCING — passed every re-run; the original failure was one-off.

The last run is stored, so get-failure can analyze it immediately afterwards.

---

Installation

Requirements:

• Node.js ≥ 20 (the server is built on MCP SDK v2 — the 2026-07-28 spec line)
• A project with @playwright/test installed and browsers available (npx playwright install chromium)

No npm account needed — install straight from GitHub (the prepare script builds dist/ automatically on install):

npx -y github:trajectiq-ai/E2E
npm install -D github:trajectiq-ai/E2E @playwright/test   # or as a project dependency
npx playwright install chromium

Or grab the packaged tarball from the repo's GitHub Releases page and install it locally:

npm install -D https://github.com/trajectiq-ai/E2E/releases/download/v0.1.0/playwright-e2e-mcp-0.1.0.tgz

Listed in the official MCP Registry as io.github.trajectiq-ai/E2E — registry-aware clients discover it there, and every v* release tag republishes the entry from CI via server.json.

MCP client configuration

Claude Code / generic (project-scoped):

{
  "mcpServers": {
    "playwright-e2e": {
      "command": "npx",
      "args": ["-y", "github:trajectiq-ai/E2E"],
      "env": { "PW_MCP_PROJECT_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

Claude Desktop / Cursor / Windsurf: add the same block to their MCP config file. The server uses its working directory as the project root; set PW_MCP_PROJECT_ROOT when the client launches it somewhere else (e.g. your home directory).

Codex / VS Code / Copilot CLIs:

codex mcp add playwright-e2e -- npx -y github:trajectiq-ai/E2E
code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","github:trajectiq-ai/E2E"]}'

Codex's defaults fight this server: the first launch clones the repo and runs tsc (measured 30 s on a cold npx cache, against a 10 s startup_timeout_sec default), and a Playwright run with retries beats the 60 s tool_timeout_sec default. Raise both in ~/.codex/config.toml:

[mcp_servers.playwright-e2e]
command = "npx"
args = ["-y", "github:trajectiq-ai/E2E"]
startup_timeout_sec = 60
tool_timeout_sec = 600

Claude Desktop (one-click): download and double-click the .mcpb Desktop Extension attached to the latest release — the bundle ships its own dependencies, so no Node setup is required. On install it prompts once for your project root (defaults to your home folder) and wires it into PW_MCP_PROJECT_ROOT, so the tools point at a real project from the first call.

Claude Code:

claude mcp add playwright-e2e -- npx -y github:trajectiq-ai/E2E

Gemini CLI / Qwen Code: paste the mcpServers block above into .gemini/settings.json (Qwen Code: .qwen/settings.json) — both speak the same MCP settings format.

Freebuff / Codebuff (project-scoped): this repo ships a committed .agents/mcp.json, so opening the checkout in Freebuff attaches the server workspace-wide — no global config needed. Your own projects can do the same: drop an mcp.json with the block above into their .agents/ directory. Freebuff asks you to trust a repository's .agents/ on first run.

All tools ship MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can show accurate safety prompts before running anything.

From a local checkout:

{
  "mcpServers": {
    "playwright-e2e": {
      "command": "node",
      "args": ["/path/to/playwright-e2e-mcp/dist/index.js"],
      "env": { "PW_MCP_PROJECT_ROOT": "/path/to/your/project" }
    }
  }
}

Hosted endpoint (ChatGPT & remote clients)

Some clients — ChatGPT custom connectors especially — only accept remote HTTPS MCP servers and refuse to spawn a local npx process. This repo ships a Streamable HTTP bridge for exactly that case:

The bridge runs the same createServer() as the stdio transport; the SDK serves every request with a fresh server instance, which is what a serverless function wants. test/http-bridge.test.mjs drives the real Node adapter over node:http so a broken bridge fails in CI, not in ChatGPT.

Add it to ChatGPT: Settings → Connectors → turn on Advanced → Developer mode → Create custom connector → paste the endpoint above → authentication None.

Codex can also take the remote transport instead of spawning npx, if you'd rather not ship Playwright to every machine:

codex mcp add playwright-e2e-remote --url https://playwright-e2e-mcp.vercel.app/api/mcp

What to expect: list-tests works and reports the specs bundled with the deployment. Tools that spawn a browser (run-test, inspect-page, validate-selector, diagnose-flaky, …) cannot download Chromium in a serverless function, so they return their normal NO_PLAYWRIGHT hint. Use the stdio install for real runs; the hosted endpoint is for discovery and for clients that cannot run local processes.

# verify the handshake without any client
curl -X POST https://playwright-e2e-mcp.vercel.app/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Redeploy after a change:

npx vercel deploy --yes --prod --token="$VERCEL_TOKEN"

Configuration

Logs always go to stderr — stdout is reserved for the MCP protocol.

Typical workflow

1. generate-e2e-test { "description": "checkout with a saved card" } — scaffolds a spec from your real selectors (skipped if you write the test yourself).
2. list-tests — see what exists (tests/checkout.spec.ts:5 checkout › pays with card).
3. run-test { "testFiles": ["tests/checkout.spec.ts"] } — run it; get stats + failures (flaky tests are auto-retried once before being called failures).
4. get-failure { "index": 1 } — read the code frame, expected/actual, the DOM snapshot at failure from the trace, the failed network requests, the page's console errors, and next steps.
5. If it looks selector-related: inspect-page { "url": "http://localhost:3000/checkout" } to see the real DOM, then validate-selector to prove the replacement selector works.
6. After changing CSS/components: compare-visual-state { "url": "…", "name": "checkout" } to catch unintended visual regressions.
7. If a failure looks intermittent: diagnose-flaky { "runs": 3 } — get the evidence verdict (flaky vs consistently broken) before deciding what to fix.
8. Fix the spec or the app, then re-run only what failed: run-test { "lastFailed": true }, and repeat until green.

Edge cases handled

Security notes

• No shell: Playwright is spawned as node <playwright/cli.js> … with an argument array — no command interpolation.
• Path sandbox: user paths are resolved lexically and must stay inside the project root.
• Cleanup: temp report/script files are written to the OS temp dir and removed; child processes are tracked and killed on shutdown.

Development

src/
├── index.ts            # bin entry point (--version/--help, main-module guard)
├── server.ts           # McpServer setup, tool registration, shutdown handling
├── tools/              # the eight tools + shared plumbing
├── utils/              # playwright-runner, report-parser, project-detector, path-utils,
│                       # logger, trace-reader (trace.zip → DOM/network/console),
│                       # image-diff (PNG codec + pixel diff), change-analyzer
└── types/              # shared interfaces and the ErrorKind taxonomy

Built on @modelcontextprotocol/server v2 (the 2026-07-28 MCP spec line) with Zod v4 standard schemas; every tool declares spec tool annotations.

npm install
npm run build   # tsc → dist/ (zero errors)
npm test        # build + test/run-tests.mjs (70 unit tests, any Node ≥20)
npm run e2e     # build + e2e/run.mjs: live MCP ↔ Playwright integration suite

Tests cover the report parser (sample Playwright JSON, trace attachments), path utils (Windows and macOS paths, sandboxing), the project detector (temp-dir fixtures: config discovery, multiple configs, missing install, test-file scanning), the shared tool helpers, the trace reader (synthetic trace.zip: error, failed action, DOM snapshot, *.network failed-request parsing, console error/warning events), the image diff (PNG round-trip, regions, color shift, dimension changes), the change analyzer (selector extraction, git + mtime paths) and the flaky verdict logic (failure signatures, CONSISTENTLY FAILING / FLAKY / NOT REPRODUCING / NO TESTS RAN).

Integration suite (npm run e2e)

Unit tests prove the logic; the integration suite proves the loop. It boots the real server over stdio against a live fixture app and a Playwright project under e2e/fixture/, then drives it exactly like an MCP client and asserts ~40 behaviours that only appear end-to-end:

• initialize handshake, 8 tools, spec tool annotations and object input schemas,
• live DOM inspection, CSS selector validation (matches, zero matches, engine syntax, parse errors), dead-server detection,
• visual regression: baseline → unchanged compare → blue → red diff detection,
• run-test pass/fail/lastFailed stats and meta lines,
• get-failure trace diagnostics: DOM at failure, the 404 network request, the console.error message, diagnosis and next steps,
• auto-retry turning a first-run failure into PASSED (1 flaky),
• diagnose-flaky verdict FLAKY (2 of 3 runs) with retries disabled,
• generate-e2e-test writing its scaffold, plus error paths (missing test path, unknown tool, unreachable server).

First run needs the browser once: npx playwright install chromium. CI runs the suite on Ubuntu and Windows (see .github/workflows/ci.yml).

Try the example

With Playwright installed in your project:

npx playwright test examples/sample-test.spec.ts

or ask your agent to call run-test with "testFiles": ["examples/sample-test.spec.ts"] — it hits the public example.com page, so it verifies browsers, network and the MCP pipeline in one shot.

License

MIT