Web Accessibility MCP Server
An MCP (Model Context Protocol) server that provides web accessibility analysis capabilities using axe-core and Puppeteer.
Features
- Analyze web accessibility of any URL using axe-core
- Simulate color blindness (protanopia, deuteranopia, tritanopia) using color matrices
- Detailed reporting of accessibility violations
- Support for custom user agents and selectors
- Debug logging for troubleshooting
- Comprehensive accessibility checks based on WCAG guidelines
Prerequisites
- Node.js (v14 or higher)
- npm
Installation
Installing via Smithery
To install Web Accessibility MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @bilhasry-deriv/mcp-web-a11y --client claude
Manual Installation
- Clone the repository:
git clone [repository-url]
cd mcp-web-a11y
- Install dependencies:
- Build the server:
Configuration
Add the server to your MCP settings file (typically located at ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):
{
"mcpServers": {
"web-a11y": {
"command": "node",
"args": ["/path/to/mcp-web-a11y/build/index.js"],
"disabled": false,
"autoApprove": [],
"env": {
"MCP_OUTPUT_DIR": "/path/to/output/directory"
}
}
}
}
Environment Variables
MCP_OUTPUT_DIR: Directory where screenshot outputs will be saved- Required for the
simulate_colorblind tool - If not specified, defaults to './output' relative to the current working directory
- Must be an absolute path when configured in MCP settings
Usage
The server provides two tools: check_accessibility for analyzing web accessibility and simulate_colorblind for simulating color blindness.
Checks the accessibility of a given URL using axe-core.
Parameters
url (required): The URL to analyzewaitForSelector (optional): CSS selector to wait for before analysisuserAgent (optional): Custom user agent string for the request
Example Usage
<use_mcp_tool>
<server_name>mcp-web-a11y</server_name>
<tool_name>check_accessibility</tool_name>
<arguments>
{
"url": "https://example.com",
"waitForSelector": ".main-content",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
}
</arguments>
</use_mcp_tool>
Simulates how a webpage appears to users with different types of color blindness using color matrix transformations.
Color Blindness Types
The tool supports three types of color blindness simulation:
- Protanopia (red-blind) - Uses matrix:
0.567, 0.433, 0
0.558, 0.442, 0
0, 0.242, 0.758
- Deuteranopia (green-blind) - Uses matrix:
0.625, 0.375, 0
0.7, 0.3, 0
0, 0.3, 0.7
- Tritanopia (blue-blind) - Uses matrix:
0.95, 0.05, 0
0, 0.433, 0.567
0, 0.475, 0.525
Parameters
url (required): The URL to capturetype (required): Type of color blindness to simulate ('protanopia', 'deuteranopia', or 'tritanopia')outputPath (optional): Custom path for the screenshot outputuserAgent (optional): Custom user agent string for the request
Example Usage
<use_mcp_tool>
<server_name>mcp-web-a11y</server_name>
<tool_name>simulate_colorblind</tool_name>
<arguments>
{
"url": "https://example.com",
"type": "deuteranopia",
"outputPath": "colorblind_simulation.png"
}
</arguments>
</use_mcp_tool>
check_accessibility Response
{
"url": "analyzed-url",
"timestamp": "ISO-timestamp",
"violations": [
{
"impact": "serious|critical|moderate|minor",
"description": "Description of the violation",
"help": "Help text explaining the issue",
"helpUrl": "URL to detailed documentation",
"nodes": [
{
"html": "HTML of the affected element",
"failureSummary": "Summary of what needs to be fixed"
}
]
}
],
"passes": 42,
"inapplicable": 45,
"incomplete": 3
}
simulate_colorblind Response
{
"url": "analyzed-url",
"type": "colorblind-type",
"outputPath": "path/to/screenshot.png",
"timestamp": "ISO-timestamp",
"message": "Screenshot saved with [type] simulation"
}
Error Handling
The server includes comprehensive error handling for common scenarios:
- Network errors
- Invalid URLs
- Timeout issues
- DNS resolution problems
Error responses will include detailed messages to help diagnose the issue.
Development
Project Structure
mcp-web-a11y/
├── src/
│ └── index.ts # Main server implementation
├── build/ # Compiled JavaScript
├── output/ # Generated screenshots
├── package.json # Project dependencies and scripts
└── tsconfig.json # TypeScript configuration
Building
This will:
- Compile TypeScript to JavaScript
- Make the output file executable
- Place the compiled files in the
build directory
Debugging
The server includes detailed debug logging that can be observed in the console output. This includes:
- Network requests and responses
- Page loading status
- Selector waiting status
- Any console messages from the analyzed page
- Color simulation progress
Common Issues and Solutions
- Timeout Errors
- Increase the timeout value in the code
- Check network connectivity
- Verify the URL is accessible
- DNS Resolution Errors
- Verify the URL is correct
- Check network connectivity
- Try using the www subdomain
- Selector Not Found
- Verify the selector exists on the page
- Wait for dynamic content to load
- Check the page source for the correct selector
- Color Simulation Issues
- Ensure the page's colors are specified in a supported format (RGB, RGBA, or HEX)
- Check if the page uses dynamic color changes (may require additional wait time)
- Verify the screenshot output directory exists and is writable
Contributing
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.