accessibility-mcp-server

jbuchan/accessibility-mcp-server

3.2

If you are the rightful owner of accessibility-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Accessibility MCP Server is designed for automated accessibility testing using Playwright and axe-core, ensuring compliance with WCAG standards.

Tools
3
Resources
0
Prompts
0

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