m2-res_588p.mp4
A11y MCP is an MCP (Model Context Protocol) server that gives LLMs access to web accessibility testing APIs.
This server uses the Deque Axe-core API and Puppeteer to allow LLMs to analyze web content for WCAG compliance and identify accessibility issues.
Note: This is not an official MCP server from Deque Labs.
- Test web pages: Test any public URL for accessibility issues with customizable viewport dimensions
- Test HTML snippets: Test raw HTML strings for accessibility issues
- WCAG compliance testing: Check content against various WCAG standards (2.0, 2.1, 2.2)
- Customizable tests: Specify which accessibility tags/standards to test against
- Rule exploration: Get information about available accessibility rules
- Color contrast analysis: Check color combinations for WCAG compliance
- ARIA validation: Test proper usage of ARIA attributes
- Orientation lock detection: Identify content that forces specific screen orientations
- Node.js 18 or later
- An MCP-compatible client (Claude Desktop, Claude Code, VS Code, Cursor, etc.)
Edit your MCP configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add the server to the mcpServers object:
{
"mcpServers": {
"a11y-accessibility": {
"command": "npx",
"args": ["-y", "a11y-mcp-server"]
}
}
}claude mcp add a11y-accessibility -- npx -y a11y-mcp-serverThis registers the server for the current project. To make it available across all projects:
claude mcp add --scope user a11y-accessibility -- npx -y a11y-mcp-serverVerify the server is registered:
claude mcp listNote: MCP tools become available after restarting your Claude Code session.
Add to your VS Code settings.json or .vscode/settings.json:
{
"mcp": {
"servers": {
"a11y-accessibility": {
"command": "npx",
"args": ["-y", "a11y-mcp-server"]
}
}
}
}Add to your Cursor MCP configuration (.cursor/mcp.json):
{
"mcpServers": {
"a11y-accessibility": {
"command": "npx",
"args": ["-y", "a11y-mcp-server"]
}
}
}Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"a11y-accessibility": {
"command": "npx",
"args": ["-y", "a11y-mcp-server"]
}
}
}Tests a URL for accessibility issues.
Parameters:
| Parameter | Required | Description |
|---|---|---|
url |
Yes | The URL of the web page to test |
tags |
No | Array of WCAG tags to test against (e.g., ["wcag2aa"]) |
width |
No | Viewport width in pixels (default: 1280) |
height |
No | Viewport height in pixels (default: 800) |
Example — desktop viewport (default):
{
"url": "https://example.com",
"tags": ["wcag2aa"]
}Example — mobile viewport (iPhone 12/13):
{
"url": "https://example.com",
"tags": ["wcag2aa"],
"width": 390,
"height": 844
}Tests an HTML string for accessibility issues.
Parameters:
| Parameter | Required | Description |
|---|---|---|
html |
Yes | The HTML content to test |
tags |
No | Array of WCAG tags to test against (e.g., ["wcag2aa"]) |
width |
No | Viewport width in pixels (default: 1280) |
height |
No | Viewport height in pixels (default: 800) |
Example — default viewport:
{
"html": "<div><img src='image.jpg'></div>",
"tags": ["wcag2aa"]
}Example — mobile viewport:
{
"html": "<div><img src='image.jpg'></div>",
"tags": ["wcag2aa"],
"width": 375,
"height": 812
}Get information about available accessibility rules with optional filtering. Returns an array of rule objects, each containing ruleId, description, help, helpUrl, and tags.
Parameters:
| Parameter | Required | Description |
|---|---|---|
tags |
No | Filter rules by tags (e.g., ["wcag2a", "wcag2aa", "best-practice"]) |
Example — filter rules by WCAG 2.1 AA:
{
"tags": ["wcag21aa"]
}Example — get all rules (no filter):
{}Check if a foreground and background color combination meets WCAG contrast requirements.
Parameters:
| Parameter | Required | Description |
|---|---|---|
foreground |
Yes | Foreground color (e.g., "#000000", "rgb(0,0,0)") |
background |
Yes | Background color (e.g., "#FFFFFF", "rgb(255,255,255)") |
fontSize |
No | Font size in pixels (default: 16) |
isBold |
No | Whether the text is bold (default: false) |
Example:
{
"foreground": "#777777",
"background": "#EEEEEE",
"fontSize": 16,
"isBold": false
}Check if ARIA attributes are used correctly in HTML.
Parameters:
| Parameter | Required | Description |
|---|---|---|
html |
Yes | HTML content to test for ARIA attribute usage |
Example:
{
"html": "<div role='button' aria-pressed='false'>Click me</div>"
}Check if content forces a specific orientation.
Parameters:
| Parameter | Required | Description |
|---|---|---|
html |
Yes | HTML content to test for orientation lock issues |
Example:
{
"html": "<html><head><meta name='viewport' content='width=device-width, orientation=portrait'></head><body>Content</body></html>"
}The server returns accessibility test results in structured JSON:
{
"violations": [
{
"id": "color-contrast",
"impact": "serious",
"description": "Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds",
"help": "Elements must meet minimum color contrast ratio thresholds",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast",
"affectedNodes": [
{
"html": "<div style=\"color: #aaa; background-color: #eee;\">Low contrast text</div>",
"target": ["div"],
"failureSummary": "Fix any of the following: Element has insufficient color contrast of 1.98 (foreground color: #aaa, background color: #eee, font size: 12.0pt, font weight: normal)"
}
]
}
],
"passes": 1,
"incomplete": 0,
"inapplicable": 2,
"timestamp": "2025-04-25T16:45:33.655Z",
"url": "about:blank",
"testEngine": {
"name": "axe-core",
"version": "4.10.3"
}
}Common tags you can use with the tags parameter:
| Tag | Description |
|---|---|
wcag2a |
WCAG 2.0 Level A |
wcag2aa |
WCAG 2.0 Level AA |
wcag2aaa |
WCAG 2.0 Level AAA |
wcag21a |
WCAG 2.1 Level A |
wcag21aa |
WCAG 2.1 Level AA |
wcag22aa |
WCAG 2.2 Level AA |
best-practice |
Best practices (not strictly WCAG) |
MIT
