# Playwright E2E MCP [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/trajectiq-ai/E2E  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1022  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/playwright-e2e-mcp

## Description
Diagnose and fix failing Playwright tests: trace analysis, verified locator fixes, flaky ranking.

## Tools
Capabilities this server exposes over MCP:

- **run-test** — Run the project's Playwright tests: stats plus each failure's file:line, kind and message. Diagnoses missing installs, dead dev servers, syntax errors, crashes and timeouts (kills the tree, keeps partial results). Reports progress; background: true returns a run id for long suites. Runs are recorded for analyze-history.
- **get-run-status** — Progress (tests done/total, failures so far) or the final result of a run-test background run; the result becomes the last run for get-failure. waitSeconds waits; cancel stops it. Default: the latest run.
- **get-failure** — Analyze one failure from the most recent run-test execution: full message and code frame, expected vs actual, stack trace, failed network requests (4xx/5xx and dead endpoints), console errors, failure kind (assertion/timeout/browser-crash/syntax/config/server-unreachable) and concrete next steps. Use run-test first.
- **suggest-fix** — Patch a failure from the last run: a drifted locator is matched against the DOM at failure (trace, or live url) and replaced with one proven unique; changed copy gets the new expected text. Returns a diff and confidence; apply: true writes it, re-runs the test and reverts if still red. Refuses when the element is truly missing (app bug).
- **inspect-page** — Open a URL headlessly and return its elements with Playwright locators proven unique on the page (role + name first), CSS selectors, visibility, text and console messages. storageState/headers open it signed in; actions click/fill first to reach a state. view 'locators' is the compact map.
- **list-tests** — List the Playwright tests available in the project (file, line, full title, projects), with optional filtering. Uses `playwright test --list` when Playwright works and falls back to a source scan when the install or config is broken, reporting why.
- **validate-selector** — Check a CSS selector, Playwright selector or locator (getByRole/getByTestId…, .first(), .filter()) on a live page: validity, match count (actions need exactly 1), sample matches and a sturdier verified locator for each. Accepts storageState/headers/actions.
- **audit-accessibility** — Run axe-core on a live page (WCAG 2.2 AA by default) and return violations worst first, each with the offending elements as verified Playwright locators, the fix, and a regression check to paste into a spec. Accepts storageState/headers/actions to audit pages behind a login or after a step.
- **generate-e2e-test** — Scaffold a Playwright test from a description using the project's REAL selectors. Scans the agent's recent file changes (git working tree / last commit, mtime fallback), extracts data-testid / role / label / placeholder / id locators with their source locations, optionally cross-checks them against the live page, writes a ready-to-run spec, and returns next steps.
- **compare-visual-state** — Visual regression check: screenshot a live page (or element), compare it to a stored baseline, and report how many pixels changed, WHERE they changed (bounding regions), and the average color shift ("blue → red"). First call saves the baseline; later calls compare. Writes a red-highlighted diff image for review.
- **diagnose-flaky** — Repeat failing tests with retries disabled and return a per-test, evidence-based verdict: CONSISTENTLY FAILING (real bug), FLAKY (pass/fail counts, error-signature variance, duration spread) or NOT REPRODUCING. Runs all repetitions in one process by default. `isolate: true` also re-runs the failures with one worker to tell parallelism bugs (shared state) from flakiness inside the test; `order: true` (Playwright 1.64+) runs the files in random orders to catch tests that depend on what ran before them. Defaults to the tests that failed in the most recent run.
- **analyze-history** — Analyze the local run history (.playwright-e2e-mcp/history.jsonl, written by every run): 'flaky' ranks tests that flip pass/fail and lists broken or regressed ones; 'patterns' groups failures by cause; 'test' shows one test's timeline.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `PW_MCP_STORAGE_STATE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Playwright E2E MCP does

Playwright E2E MCP MCP server connects an MCP client to a project’s Playwright test suite and the pages those tests exercise. It covers the workflow from finding a test and running it to inspecting a failure, checking whether a selector still matches, and applying a verified repair. It also records local run history for later flakiness and regression analysis.

The server is intended to complement a browser-driving MCP, not replace one. Browser-driving tools handle exploratory interaction; this server focuses on test execution, diagnostics, selector evidence, and changes that can be re-tested.

## How it works

A typical repair flow starts with `run-test`. The result includes statistics, failure locations, diagnostic categories, and hints. For longer suites, a background run returns an identifier that `get-run-status` can monitor, wait on, or cancel.

`get-failure` uses the Playwright trace to inspect the page as it existed at the failure. Its analysis can include the stack, expected and actual values, a DOM snapshot, failed HTTP requests, console errors, and suggested next steps. `suggest-fix` compares the failing locator with that evidence. If it finds a unique suitable element, it can replace the locator or update changed expected text. With `apply: true`, it writes the change, reruns the test, and restores the original edit if the test remains red.

Every run is stored locally. `diagnose-flaky` repeats a test two to ten times with retries disabled and reports whether it consistently fails, is flaky, or does not reproduce. `analyze-history` ranks flaky, regressed, and broken tests, groups failures by cause, or displays one test’s timeline.

## Setup and configuration

The canonical installation uses npm through `npx -y playwright-e2e-mcp`. A GitHub release reference can also be pinned with `npx -y github:trajectiq-ai/E2E#v0.2.2`. Claude Desktop users can install the released `.mcpb` extension, and remote-only clients can connect to the documented hosted MCP endpoint. The MCP Registry identifier is `io.github.trajectiq-ai/E2E`.

For local setup, the server needs access to the Playwright project and its configuration. `run-test` accepts a project root, test files or directories, title filtering, browser project, headed mode, worker and retry settings, timeouts, and a configuration path or index.

Page-oriented operations can use a Playwright `storageState` JSON file, extra request headers, a viewport, and up to 20 post-load actions such as clicks, fills, navigation, waits, and key presses. The storage-state path may be supplied directly or through `PW_MCP_STORAGE_STATE`. This supports pages requiring an existing login session without embedding credentials in the tool call.

## Tools and capabilities

The Playwright E2E MCP MCP server exposes these capabilities:

- Run tests, monitor background runs, and list tests with file, line, title, and project information.
- Inspect a page and return visible elements, text, CSS selectors, console output, and verified Playwright locators.
- Validate CSS selectors, Playwright selectors, and locator expressions against a live page, including match counts and sturdier alternatives.
- Generate a Playwright test from a description using selectors found on the live page.
- Compare before-and-after visual states and report moved content and color changes.
- Analyze failures, apply verified fixes, and classify flaky behavior from repeated runs or local history.

## Limitations and notes

This tool does not provide an exploratory, step-by-step browsing session. Use a browser-driving MCP for that role. It also does not replace Playwright’s own planner, generator, and healer agents inside VS Code.

A proposed locator fix is not a guarantee that the application is correct. When the expected element is genuinely absent, `suggest-fix` refuses to patch the test rather than hiding the application defect. Background runs can return partial results when their hard wall-clock limit is reached. A page action failure reports the failed step and how many actions completed before it.

_Full upstream README: https://allmcps.com/mcp/playwright-e2e-mcp/readme_