Playwright Debug MCP Server

An MCP (Model Context Protocol) server designed to supercharge AI-assisted debugging of Playwright tests.

Instead of manually downloading and scrubbing through trace.zip files to find why a test failed, simply point this MCP server to your trace file or Playwright results directory. The server instantly parses the exact failing action, action history, network failures, DOM snapshots, and screenshots so your AI assistant (like Claude, Cursor, Cline, or Antigravity) can instantly pinpoint the failure and suggest a code fix.

Features

• 🐛 analyze_trace: Automatically extracts the exact action that hung or failed, the selector used, DOM snapshots, and Base64 screenshots.

• 📜 get_action_history: Extracts a full chronological timeline of every user action performed during the test.

• 🌐 get_network_log: Filters network requests inside the trace to find exactly what APIs returned 4xx or 5xx right before the crash.

• 🖼️ get_screenshots_around_time: Visual timeline extraction tool for the AI to view the exact state of the browser before and after any given timestamp.

• 🛠️ suggest_fix: A built-in logic engine mapping common Playwright errors to actionable fixes.

Related MCP server: LocatorLabs MCP Server

Why Use This MCP?

Debugging failed E2E tests often involves tedious, manual steps: downloading the trace artifact from CI, opening it locally via playwright show-trace, and manually scrubbing through a timeline to see what happened. By the time you figure out the issue, valuable time has been wasted.

This MCP bridges the gap between raw test output and AI problem-solving. By giving your AI direct programmatic access to Playwright's trace files, the AI can instantly inspect the DOM, network requests, screenshots, and action history. Instead of guessing why a test failed based on a stack trace, your AI assistant can actually "see" the exact browser state at the moment of failure.

Use Cases

• CI/CD Pipeline Debugging: Quickly understand why a test failed in the CI environment without downloading heavy artifacts. Just provide the path to the trace file to your AI assistant.

• Tackling Flaky Tests: The AI can analyze action history and network logs to identify race conditions or missing wait states that cause intermittent failures.

• Local Test Authoring & Fixing: When writing tests locally, easily feed trace results to Cursor, Claude, or Cline to get an instant, contextual fix (e.g., "Ah, the button was obscured by a modal, use force: true or wait for the modal to close").

• Learning & Onboarding: Helps junior QA engineers and developers learn Playwright best practices through AI-guided analysis and fix suggestions.

Benefits for Testers and Teams

• Massive Time Savings: Eliminate the 5-10 minutes usually spent manually downloading, extracting, and loading trace files for every single test failure.

• Reduced Context Switching: Debug tests directly within your IDE using your preferred AI assistant instead of constantly switching between your editor, terminal, and browser trace viewer.

• Actionable Insights: It doesn't just surface errors; the built-in suggest_fix logic provides concrete code suggestions to resolve common Playwright pitfalls (like strict mode violations or detached DOM elements).

• Boosted Developer Velocity: Automated extraction of DOM snapshots and screenshots allows teams to fix broken tests immediately, keeping the build green and deploying faster.

Usage for the Public (VS Code, Cursor, Claude Desktop)

This server can be used out-of-the-box by any MCP-compatible AI agent without needing to clone or configure anything locally.

Using in Cursor

1. Go to Cursor Settings > Features > MCP Servers

2. Click + Add New MCP Server

3. Set Type to command

4. Set Name to playwright-debug

5. Set Command to:

   npx -y github:aakarshitsharma06/playwright-debug-mcp

Using in VS Code (with Cline / RooCode extension)

Open your MCP configuration file (usually in ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json) and add:

{
  "mcpServers": {
    "playwright-debugger": {
      "command": "npx",
      "args": ["-y", "github:aakarshitsharma06/playwright-debug-mcp"]
    }
  }
}

Using in Claude Desktop

Open your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "playwright-debugger": {
      "command": "npx",
      "args": ["-y", "github:aakarshitsharma06/playwright-debug-mcp"]
    }
  }
}

How to Build Locally

If you want to modify or run the code locally:

npm install
npm run build
node dist/index.js