Playwright Accessibility Testing MCP Server

A production-ready Model Context Protocol (MCP) server for comprehensive accessibility testing using Playwright and axe-core. Test web applications for WCAG 2.0/2.1 compliance with ease.

Features

• Comprehensive WCAG Testing: Tests WCAG 2.0/2.1 Level A/AA compliance plus best practices
• Natural Language Testing: Find elements by visible text - no CSS selectors needed
• Auto-Discovery: Automatically discover and test all interactive elements
• Interactive Component Testing: Test across different states (dropdowns, modals, etc.)
• Screenshot Capture: Visual documentation of tested areas
• Predefined Prompts: Quick-start templates for common testing scenarios
• Production-Ready: Modular architecture, TypeScript, comprehensive error handling

Installation

npm install
npm run build

Configuration

Add to your MCP client configuration file:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "playwright-a11y": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
    }
  }
}

Claude Code (.claude/config.json in your project):

{
  "mcpServers": {
    "playwright-a11y": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
    }
  }
}

Restart your MCP client after configuration.

Quick Start

Using the Predefined Prompt (Easiest!)

The fastest way to test is with the comprehensive-a11y-test prompt:

Use comprehensive-a11y-test prompt:
- url: https://example.com
- block: Rewards account
- steps: open menu, select provider, input value, click apply

Parameters:

• url (required): URL to test
• block (optional): Section name (e.g., "Navigation", "User Profile")
• steps (optional): Comma-separated interaction steps

What it does:

1. Navigates to the URL
2. Runs full accessibility audit
3. Tests specified section with auto-discovery or custom steps
4. Generates human-readable report with:
   • Executive summary
   • Critical/serious/moderate/minor issues
   • Prioritized fix recommendations

Available Tools

1. a11y_scanUrl

Scan a URL for accessibility violations.

Parameters:

{
  url: string;              // Required: URL to scan
  selector?: string;        // Optional: CSS selector to scan specific element
  waitForSelector?: string; // Optional: Wait for this element before scanning
  captureScreenshot?: boolean; // Optional: Capture screenshot (default: false)
  timeout?: number;         // Optional: Navigation timeout in ms (default: 30000)
}

Example:

{
  "url": "https://example.com",
  "selector": "header nav",
  "captureScreenshot": true
}

2. a11y_scanInteractiveByText

Test components using natural language - no CSS selectors needed!

Parameters:

{
  url: string;              // Required: URL to navigate to
  containerText: string;    // Required: Visible text to find section (e.g., "Rewards")
  autoDiscover?: boolean;   // Optional: Auto-discover interactions (default: true)
  customInteractions?: Array<{
    stateName: string;      // Name for this interaction
    elementText: string;    // Visible text of element to interact with
    action: "click" | "hover" | "focus";
    waitAfter?: number;     // Wait time in ms (default: 500)
  }>;
  captureScreenshots?: boolean; // Optional: Screenshot each state
  timeout?: number;         // Optional: Navigation timeout in ms
}

Example: Auto-discover everything

{
  "url": "https://example.com",
  "containerText": "User Menu",
  "autoDiscover": true,
  "captureScreenshots": true
}

Example: Custom interactions

{
  "url": "https://example.com",
  "containerText": "Rewards",
  "customInteractions": [
    {
      "stateName": "After opening menu",
      "elementText": "View Details",
      "action": "click"
    }
  ]
}

Response Format

Scan Result

{
  "url": "https://example.com",
  "timestamp": "2025-01-28T...",
  "summary": {
    "violations": 3,
    "passes": 12,
    "incomplete": 1
  },
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "Elements must have sufficient color contrast",
      "help": "Ensure contrast ratio is at least 4.5:1",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.4/color-contrast",
      "tags": ["wcag2aa", "wcag21aa"],
      "nodes": [
        {
          "html": "<button class=\"btn\">Submit</button>",
          "target": [".btn"],
          "failureSummary": "..."
        }
      ]
    }
  ],
  "screenshotPath": "/path/to/screenshot.png"
}

Interactive Scan Result

{
  "url": "https://example.com",
  "containerText": "Rewards",
  "totalStates": 3,
  "states": [
    {
      "stateName": "Initial State",
      "summary": {"violations": 0, "passes": 5, "incomplete": 0},
      "violations": []
    },
    {
      "stateName": "After interacting with buttons: \"View Details\"",
      "action": "click",
      "elementText": "View Details",
      "summary": {"violations": 2, "passes": 8, "incomplete": 1},
      "violations": [...]
    }
  ]
}

Project Structure

server/
├── constants/          # Configuration and constants
│   ├── config.ts      # Application configuration
│   ├── selectors.ts   # Interactive element selectors
│   └── wcag-tags.ts   # WCAG compliance tags
├── types/             # TypeScript type definitions
│   └── scan-result.ts # Scan result interfaces
├── utils/             # Utility functions
│   ├── axe-scanner.ts      # Axe configuration and scanning
│   ├── browser.ts          # Browser management
│   ├── container-finder.ts # Find elements by text
│   └── screenshot.ts       # Screenshot utilities
├── tools/             # Tool implementations
│   ├── scan-url.ts                   # URL scanning tool
│   └── scan-interactive-by-text.ts   # Interactive testing tool
├── prompts/           # Prompt templates
│   └── comprehensive-a11y-test.ts    # Predefined test prompt
└── server.ts          # Main MCP server entry point

WCAG Compliance

This server tests for:

• WCAG 2.0 Level A (wcag2a)
• WCAG 2.0 Level AA (wcag2aa)
• WCAG 2.1 Level A (wcag21a)
• WCAG 2.1 Level AA (wcag21aa)
• Best Practices (best-practice)

Impact Levels

Violations are categorized by severity:

• Critical: Blocks access completely - fix immediately
• Serious: Creates significant barriers - fix before release
• Moderate: Noticeable issues - fix soon
• Minor: Small improvements - can be backlogged

Output Files

All screenshots are saved to: ./accessibility-screenshots/

• scan-{timestamp}.png - Full page screenshots
• {name}-{timestamp}.png - Named screenshots

Usage Examples

Test a simple page

User: "Check accessibility of https://example.com"
Claude: → Calls a11y_scanUrl
        → Returns: 3 violations (2 serious, 1 moderate)

Test specific section by name

User: "Test the Navigation menu on https://example.com"
Claude: → Calls a11y_scanInteractiveByText with containerText="Navigation"
        → Auto-discovers all interactive elements
        → Returns: Issues found in different states

Test with custom interactions

User: "Test the Rewards section - click 'View Details' then 'Redeem'"
Claude: → Parses your request
        → Calls a11y_scanInteractiveByText with custom interactions
        → Returns: Accessibility analysis for each state

Development

# Build TypeScript
npm run build

# Watch mode for development
npm run watch

# Start server directly (for testing)
npm start

Adding New Tools

1. Create tool file in server/tools/
2. Define schema and execution function
3. Register in server/server.ts

Adding New Utilities

1. Create utility file in server/utils/
2. Export functions
3. Import where needed

Best Practices

1. Always test with screenshots during initial development:

   {"captureScreenshot": true}
   

2. Wait for dynamic content on SPAs:

   {"waitForSelector": ".content-loaded"}
   

3. Test interactive components in different states:

   • Initial state
   • After user interaction
   • Error states
   • Success states

4. Use natural language testing when you don't know selectors:

   {"containerText": "User Menu", "autoDiscover": true}
   

Troubleshooting

Server not starting

npm run build
# Check config path is absolute
# Restart MCP client

Element not found

• Verify the text exists on the page
• Try a shorter, more specific text
• Check if content is loaded (use waitForSelector)

Timeout errors

{"timeout": 60000}  // Increase to 60 seconds

Requirements

• Node.js 18+
• Playwright (browsers installed automatically)

License

ISC

Contributing

1. Follow the modular architecture
2. Add TypeScript types for new features
3. Document new tools in README
4. Update constants instead of hardcoding values

---

Built for production use with modular, maintainable architecture.