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 testsget_test_results: Retrieve saved test resultslist_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 testwcagLevel(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 pointssrc/accessibility/: Core accessibility testing logicsrc/types/: TypeScript type definitionssrc/utils/: Utility functions for validation and file I/Ooutputs/: Generated test results and screenshotstests/: 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
Support
For issues and questions:
- Check the documentation
- Review existing GitHub issues
- Create a new issue with detailed information