Playwright Report MCP

An MCP (Model Context Protocol) server for running Playwright tests and reading structured results, failed test details, and attachment content — designed for AI agents doing test failure analysis.

Table of contents

• What it is
• What it is NOT
• Why
• Quick start
• Tools
• Attachments
• Installation
• Configuration
• Requirements
• Troubleshooting
• Development
• Cutting a release
• Contributing
• Release
• License

What it is

Playwright Report MCP gives an AI agent structured, token-efficient access to Playwright test outcomes. It runs your test suite, reads the JSON reporter output, and surfaces exactly what the agent needs: which tests failed, what the errors were, and the content of relevant attachments.

What it is NOT

There are many Playwright MCP servers that control a browser — they navigate pages, click elements, fill forms, and take screenshots. Playwright Report MCP is not one of those.

Why

The problem with existing approaches

Default reporters (list / dot) — Playwright's default reporters print human-readable output to stdout. Compact, but lossy: no attachment paths, no retry breakdown, no structured data.

HTML reporter (report.html) — A self-contained SPA bundle (typically 2–50 MB). Not machine-readable as text and exceeds any LLM context window.

Reading results.json directly — Works, but a full JSON report for even a small test suite is 10,000–20,000 tokens. For a failing test, most of that is passing test metadata you don't need.

What Playwright Report MCP does instead

• Filters results.json to only failed tests
• Returns structured, typed JSON the agent can act on immediately
• Exposes individual attachments by name so the agent fetches only what it needs
• Works on results produced by anyone — CI pipeline, a human, or the agent itself

Token cost comparison (one failed test in a 20-test suite)

Approximate input token counts based on Claude tokenization (~3–4 characters per token for mixed JSON/text content).

¹ Custom text attachments — e.g. AI diagnosis (~500–2,000 tokens) and console logs (~200–500 tokens) added via testInfo.attach() in your own fixtures.

² Full page HTML snapshot — a custom fixture that attaches the full rendered page HTML on failure. Large pages alone can reach 30,000–80,000 tokens and dominate cost regardless of whether MCP is used.

Key observations:

• For a live run, stdout (list/dot) is compact but gives the agent no path to attachment content — dead end for deeper analysis
• Reading results.json directly costs ~12,500–23,000 tokens even when only one test failed — most of it is passing test metadata the agent doesn't need
• The biggest MCP gains are in the middle rows: getting error messages + page state from existing results at ~4–45× lower token cost
• Full page HTML snapshot dominates cost either way; skipping it in favour of error-context is the single largest optimisation available

CI failure analysis

The primary use case: your CI pipeline runs the tests, the agent picks up the results after the fact and diagnoses failures. get_failed_tests reads results.json regardless of who triggered the run. No re-run needed.

Quick start

1. Install via npx (recommended)

No clone or build step needed — npx downloads and runs the server automatically:

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "type": "stdio"
    }
  }
}

Or build from source:

git clone https://github.com/hubertgajewski/playwright-report-mcp.git
cd playwright-report-mcp
npm install && npm run build

2. Add the JSON reporter to your Playwright project

// playwright.config.ts
reporter: [
  ['json', { outputFile: 'test-results/results.json' }],
  ['html'], // keep any existing reporters
],

3. Register in .mcp.json

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "type": "stdio"
    }
  }
}

4. Ask your AI agent

Run the Playwright tests and tell me what failed.

Compatibility

Tested with Claude Code (CLI). Should work with any MCP-compatible client that supports stdio transport, including Claude Desktop, Cursor, Cline, Windsurf, and Continue.dev — but these have not been verified.

The stdio server supports both MCP protocol eras from one entrypoint:

• Modern: protocol revision 2026-07-28, selected by clients using version negotiation (for example, versionNegotiation: { mode: "auto" }).
• Legacy: supported 2025-era revisions, selected by clients that use the traditional initialize handshake. This remains the default behavior in the MCP client SDK.

The opening exchange pins one era for the connection lifetime. A client that pins an unsupported revision receives an explicit negotiation error; the server does not silently switch it to another era.

Tools

The project-scoped tools accept an optional workingDirectory parameter — see Multi-worktree support. get_run_status can use either a runId from run_tests with wait: false, or a workingDirectory lookup for the latest tracked run.

run_tests

Runs the Playwright test suite and returns structured pass/fail results.