Playwright E2E MCP

playwright-e2e-mcp

The test doctor for AI agents.

Your Playwright test fails. Your AI finds out why, fixes it, and proves the fix works , or tells you it's a real bug.

⭐ If it saves you a debugging session, a star helps other Playwright users find it.

Quick start · Features · Tools · Tool reference · GitHub Action · Benchmark · Changelog

An MCP server and agent skill that gives Claude, Cursor, VS Code Copilot, Codex, Gemini and any other MCP client a full Playwright toolkit: a test runner, a failure detective and a fixer that checks its own work. Browser MCPs let an AI click around a page. This one lets it keep your test suite green, for TypeScript and Python suites, on your laptop and in CI. Free, MIT, no account.

❌ Without it / ✅ With it

Without it, your agent sees Timeout 5000ms exceeded waiting for getByTestId('checkout'), guesses a new selector, edits the test and hopes. Or it "fixes" the test by deleting the assertion that caught a real bug.

With it, your agent reads the page as it was when the test failed (from the Playwright trace), swaps in a locator proven unique on that page, re-runs the test and keeps the edit only if it passes. When the button is really gone, it says so: that's an app bug, not a test to patch. And a heal guard blocks any "fix" that went green by checking less.

flowchart LR

A["run-test or load-report (CI)"] --> B["get-failure DOM at failure, requests, console"] B --> C{"suggest-fix"} C -->|"locator proven on the page"| D["apply + re-run"] D -->|green| E["✅ fixed and verified"] D -->|still red| F["↩️ edit reverted"] C -->|"element really gone"| G["🐞 reported as an app bug"] D -.-> H["check-test-change blocks fixes that check less"]

⚡ Quick start

Run this in your project root. It adds the server to every MCP client config it finds (Claude Code, Cursor, VS Code, Gemini CLI, Codex), installs the agent skill and leaves your other servers alone:

npx -y playwright-e2e-mcp init      # --client all | cursor,vscode … · --dry-run

npx -y playwright-e2e-mcp doctor # checks Node, Playwright, browsers, client setup and updates

Then restart your client and ask:

Run my Playwright tests and fix whatever fails.

Or let your agent install it. Paste this into any coding agent:

Install the playwright-e2e-mcp server and skill by following

https://raw.githubusercontent.com/xsignon-secure/E2E/main/llms-install.md

Or add the standard config by hand (works in most clients):

{

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

Needs: Node.js 22+, and a project with @playwright/test and a browser (npx playwright install chromium) or with pytest-playwright. The server uses its working directory as the project root; if your client starts it elsewhere, add "env": { "PW_MCP_PROJECT_ROOT": "/path/to/your/project" }.

Claude Code

Server and skill, as a plugin:

/plugin marketplace add xsignon-secure/E2E

/plugin install playwright-e2e-mcp@xsignon-secure

Or the server only:

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

Claude Desktop

Download the .mcpb extension from the latest release and double-click it. It ships its own dependencies, so no Node setup is needed. On install it asks for your project root: choose the project folder, not your home directory.

You can also add the standard config to claude_desktop_config.json.

Cursor

Click Install in Cursor, or go to Settings → MCP → Add new MCP server and paste the standard config. For one project only, put it in .cursor/mcp.json.

Only fixing failing tests? Install the core tools only: the seven-tool fix loop (--tools=core), about 2.3k tokens of tool definitions instead of 12.1k.

VS Code / GitHub Copilot

Click the Install in VS Code button above, or run:

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

Codex

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

A Playwright run with retries can take longer than Codex's default 60 s tool timeout. Raise the timeouts in ~/.codex/config.toml:

[mcp_servers.playwright-e2e]

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

Gemini CLI / Qwen Code

Server and skill, as an extension:

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

Or paste the standard config into .gemini/settings.json (Qwen Code: .qwen/settings.json).

Windsurf, Cline, Zed, Freebuff and other clients

Add the standard config to the client's MCP config file (Cline: *MCP Servers → Configure*). Clients that take a command, such as Zed, run npx with the arguments -y playwright-e2e-mcp.

Freebuff / Codebuff: drop an mcp.json with the standard config into your project's .agents/ folder. This repo ships one in .agents/mcp.json; Freebuff asks you to trust a repository's .agents/ on first run.

ChatGPT, claude.ai and other remote-only clients

Some clients only accept a remote HTTPS server. This repo ships a Streamable HTTP bridge you can host for free on Vercel, with OAuth sign-in for claude.ai connectors (dynamic registration and Client ID Metadata Documents). See Hosted endpoint. On Vercel the page tools (inspect a page, check selectors, accessibility and Web Vitals audits) run on a bundled Chromium against public URLs. Running and fixing your own tests needs your project, so use the local install for that.

Other ways to install: skill only, Docker, registry, tarball

Updating

npx -y playwright-e2e-mcp doctor tells you whether a newer version is out and prints the command for your setup. Upgrade notes for each release are on the releases page.

💬 What you can ask

| 📈 | "What's been breaking lately?" | Ranks flaky, newly broken and slow tests from the run history and names the commit where