Web Accessibility MCP Server

An MCP server that provides web accessibility analysis capabilities using axe-core and Puppeteer.

An MCP (Model Context Protocol) server that provides web accessibility analysis capabilities using axe-core and Puppeteer.

- 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

To install Web Accessibility MCP Server for Claude Desktop automatically viaSmithery:

npx -y @smithery/cli install @bilhasry-deriv/mcp-web-a11y --client claude

git clone [repository-url] cd mcp-web-a11y

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" } } } }

- MCP_OUTPUT_DIR: Directory where screenshot outputs will be saved

- Required for thesimulate_colorblindtool
- If not specified, defaults to './output' relative to the current working directory
- Must be an absolute path when configured in MCP settings

The server provides two tools:check_accessibilityfor analyzing web accessibility andsimulate_colorblindfor simulating color blindness.

Checks the accessibility of a given URL using axe-core.

- url(required): The URL to analyze
- waitForSelector(optional): CSS selector to wait for before analysis
- userAgent(optional): Custom user agent string for the request

<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.

The tool supports three types of color blindness simulation:

0.567, 0.433, 0 0.558, 0.442, 0 0, 0.242, 0.758

Deuteranopia(green-blind) - Uses matrix:

0.95, 0.05, 0 0, 0.433, 0.567 0, 0.475, 0.525

- url(required): The URL to capture
- type(required): Type of color blindness to simulate ('protanopia', 'deuteranopia', or 'tritanopia')
- outputPath(optional): Custom path for the screenshot output
- userAgent(optional): Custom user agent string for the request

<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>

{ "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 }

{ "url": "analyzed-url", "type": "colorblind-type", "outputPath": "path/to/screenshot.png", "timestamp": "ISO-timestamp", "message": "Screenshot saved with [type] simulation" }

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.

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

- Compile TypeScript to JavaScript
- Make the output file executable
- Place the compiled files in thebuilddirectory

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

- Increase the timeout value in the code
- Check network connectivity
- Verify the URL is accessible

- Verify the URL is correct
- Check network connectivity
- Try using the www subdomain

- Verify the selector exists on the page
- Wait for dynamic content to load
- Check the page source for the correct selector

- 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
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request

This project is licensed under the MIT License - see theLICENSEfile for details.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB