Accessibility MCP Server

A Model Context Protocol (MCP) server for automated accessibility testing using Playwright and axe-core against WCAG standards.

Overview

This server provides AI agents (LLMs) with the ability to perform comprehensive accessibility audits on websites. It leverages industry-standard tools to deliver detailed reports on WCAG compliance violations and recommendations.

Features

🔍 Comprehensive Accessibility Testing

• Full WCAG 2.1/2.2 compliance checking (A, AA, AAA levels)

• Cross-browser testing (Chromium, Firefox, WebKit)

• Real browser automation with Playwright

• axe-core accessibility engine integration

🤖 MCP Integration

• Three main tools exposed to AI agents:

  • test_accessibility: Run accessibility tests

  • get_test_results: Retrieve saved test results

  • list_test_results: List all available test files

📊 Rich Reporting

• Human-readable text reports

• Raw JSON data for programmatic access

• Screenshot capture capability

• Detailed violation summaries with remediation guidance

🛡️ Security & Validation

• URL validation and sanitization

• Configuration parameter validation

• Graceful error handling

• Safe browser isolation

Installation

# Clone and install dependencies
npm install

# Install Playwright browsers
npx playwright install

# Build the project
npm run build

Usage

Starting the MCP Server

# Development mode
npm run dev

# Production mode
npm run build && npm start

The server communicates via stdin/stdout following the MCP protocol specification.

Available Tools

test_accessibility

Run an accessibility test on a website.

Parameters:

• url (required): Website URL to test

• wcagLevel (optional): 'A', 'AA', or 'AAA' (default: 'AA')

• wcagVersion (optional): '2.1' or '2.2' (default: '2.1')

• browser (optional): 'chromium', 'firefox', or 'webkit' (default: 'chromium')

• includeScreenshot (optional): boolean (default: false)

Example:

{
  "url": "https://example.com",
  "wcagLevel": "AA",
  "wcagVersion": "2.1",
  "browser": "chromium",
  "includeScreenshot": true
}

get_test_results

Retrieve saved accessibility test results.

Parameters:

• fileName (required): Name of the test result file

list_test_results

List all available test result files.

No parameters required.

Architecture

src/
├── server/           # MCP server implementation
│   ├── index.ts      # Main entry point
│   └── mcpServer.ts  # MCP protocol handlers
├── accessibility/    # Core testing engine
│   └── tester.ts     # Playwright + axe-core integration
├── types/           # TypeScript type definitions
│   └── index.ts     # Interface definitions
└── utils/           # Utility modules
    ├── fileOutput.ts    # Result file management
    └── validation.ts    # Input validation and sanitization

Development

Project Structure

• src/server/: MCP server implementation and entry points

• src/accessibility/: Core accessibility testing logic

• src/types/: TypeScript type definitions

• src/utils/: Utility functions for validation and file I/O

• outputs/: Generated test results and screenshots

• tests/: Test suites (planned)

Configuration

The server accepts various configuration options:

• WCAG Levels: A, AA, AAA

• WCAG Versions: 2.1, 2.2

• Browsers: Chromium, Firefox, WebKit

• Timeouts: 1s to 5 minutes

• Viewports: 320x200 to 4000x4000 pixels

Error Handling

The server implements comprehensive error handling:

• URL validation and sanitization

• Browser initialization failures

• Network timeout handling

• File I/O error recovery

• Graceful MCP protocol error responses

Output Formats

Text Reports

Human-readable accessibility reports including:

• Executive summary with violation counts

• Detailed violation descriptions with remediation steps

• Element-specific failure information

• WCAG success criteria references

JSON Data

Machine-readable results containing:

• Complete axe-core results

• Test metadata and configuration

• Structured violation data

• Performance metrics

Security Considerations

• URL validation prevents testing of local/private addresses

• Browser sandboxing through Playwright

• Input sanitization for all parameters

• Safe file I/O operations

• Process isolation

Cloud Deployment (Future)

This server is designed for eventual cloud deployment with:

• Container support (Docker)

• Environment-based configuration

• Database integration for result storage

• API rate limiting

• Authentication and authorization

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation

• playwright: Browser automation framework

• @axe-core/playwright: Accessibility testing integration

• axe-core: Accessibility rules engine

• typescript: Type safety and development tooling

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Submit a pull request

Support

For issues and questions:

1. Check the documentation

2. Review existing GitHub issues

3. Create a new issue with detailed information