Playwright Accessibility

This Production-ready MCP server enables comprehensive accessibility testing using Playwright and axe-core. You can automatically audit web pages for WCAG 2.0/2.1 compliance, test interactive components, capture screenshots, and generate readable reports, all within an MCP workflow.

How to use

You run this MCP server to perform accessibility tests from your MCP client. Start the server locally and configure your client to connect to it, then invoke the available testing prompts to scan URLs or interact with page components by visible text. The server exposes tools that let you scan an entire page or test specific sections through natural language prompts, with auto-discovery of interactive elements and optional state-by-state testing.

How to install

Prerequisites: Node.js 18+ must be installed on your machine. Ensure Playwright browsers are installed automatically during setup.

Install dependencies and build the MCP server into your environment.

npm install
npm run build

Configuration and environment

Configure your MCP client to connect to the Playwright accessibility MCP server. The server is started through a local stdio command so your MCP client can launch it directly.

// Claude Desktop configuration example
{
  "mcpServers": {
    "playwright_a11y": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
    }
  }
}

Usage prompts and examples

Use predefined prompts to start testing quickly. You can test a URL for full accessibility or focus on a particular page section by visible text. The prompts support auto-discovery of interactive elements and optional custom interactions.

Examples of what you can do:

# Example: Full URL accessibility scan
# Use within your MCP client to run comprehensive-a11y-test on a URL
- url: https://example.com
- block: Rewards account
- steps: open menu, select provider, input value, click apply

Output and reports

The server returns a structured report with an executive summary, a breakdown of violations by severity, and prioritized remediation recommendations. Screenshots can be captured to document tested areas.

Project structure and capabilities

The MCP server includes modules for scanning URLs, discovering and testing interactive components, and utilities for screenshot capture and reporting. It supports WCAG 2.0/2.1 Levels A/AA plus best practices and provides both full-page scans and interactive state testing.

Security and best practices

Use wait-for strategies for dynamic content, verify element visibility by text when possible, and ensure you handle timeouts gracefully to avoid flaky tests. Capture screenshots judiciously to balance storage usage with traceability.

Troubleshooting

If the MCP server fails to start, confirm Node.js is installed and that you built the server before launching. Ensure the path to the server file is correct in your MCP client configuration. Restart your MCP client after configuration changes.

Notes

This server is designed for production use with a modular TypeScript architecture and robust error handling. It includes predefined prompts to accelerate common accessibility testing workflows.

Available tools

a11y_scanUrl

Scan a URL for accessibility violations. Supports optional selector, waitForSelector, screenshot capture, and timeout to verify full-page accessibility.

a11y_scanInteractiveByText

Test components using natural language by visible text. Supports auto-discovery of interactions, custom interactions, and optional per-state screenshots.