Playwright E2E MCP

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.