Web Accessibility-Testing MCP Server (A11y MCP)

https://github.com/user-attachments/assets/316c6d44-e677-433e-b4d5-63630b4bab2b

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.

Features

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

Installation

Prerequisites

Node.js 18 or later
An MCP-compatible client (Claude Desktop, Claude Code, VS Code, Cursor, etc.)

Claude Desktop

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:

config.json

{
  "mcpServers": {
    "a11y-accessibility": {
      "command": "npx",
      "args": ["-y", "a11y-mcp-server"]
    }
  }
}

Claude Code (CLI)

Terminal

claude mcp add a11y-accessibility -- npx -y a11y-mcp-server

This registers the server for the current project. To make it available across all projects:

Terminal

claude mcp add --scope user a11y-accessibility -- npx -y a11y-mcp-server

Verify the server is registered:

Terminal

claude mcp list

Note: MCP tools become available after restarting your Claude Code session.

VS Code (Copilot)

Add to your VS Code settings.json or .vscode/settings.json:

config.json

{
  "mcp": {
    "servers": {
      "a11y-accessibility": {
        "command": "npx",
        "args": ["-y", "a11y-mcp-server"]
      }
    }
  }
}

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json):

config.json

{
  "mcpServers": {
    "a11y-accessibility": {
      "command": "npx",
      "args": ["-y", "a11y-mcp-server"]
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

config.json

{
  "mcpServers": {
    "a11y-accessibility": {
      "command": "npx",
      "args": ["-y", "a11y-mcp-server"]
    }
  }
}

Available Tools

test_accessibility

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

config.json

{
  "url": "https://example.com",
  "tags": ["wcag2aa"]
}

Example — mobile viewport (iPhone 12/13):

config.json

{
  "url": "https://example.com",
  "tags": ["wcag2aa"],
  "width": 390,
  "height": 844
}

test_html_string

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:

config.json

{
  "html": "<div><img src='image.jpg'></div>",
  "tags": ["wcag2aa"]
}

Example — mobile viewport:

config.json

{
  "html": "<div><img src='image.jpg'></div>",
  "tags": ["wcag2aa"],
  "width": 375,
  "height": 812
}

get_rules

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:

config.json

{
  "tags": ["wcag21aa"]
}

Example — get all rules (no filter):

config.json

{}

check_color_contrast

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:

config.json

{
  "foreground": "#777777",
  "background": "#EEEEEE",
  "fontSize": 16,
  "isBold": false
}

check_aria_attributes

Check if ARIA attributes are used correctly in HTML.

Parameters:

Parameter	Required	Description
`html`	Yes	HTML content to test for ARIA attribute usage

Example:

config.json

{
  "html": "<div role='button' aria-pressed='false'>Click me</div>"
}

check_orientation_lock

Check if content forces a specific orientation.

Parameters:

Parameter	Required	Description
`html`	Yes	HTML content to test for orientation lock issues

Example:

config.json

{
  "html": "<html><head><meta name='viewport' content='width=device-width, orientation=portrait'></head><body>Content</body></html>"
}

Response Format

The server returns accessibility test results in structured JSON:

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

WCAG Tags Reference

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)

Dependencies

License

MIT