Run WCAG accessibility scans and contrast checks via a11y-mcp-server (npx)
a11y-mcp-server v1.1.0 wraps Axe-core 4.11.4 + Puppeteer into 6 MCP tools for accessibility testing over stdio. Zero config: npx -y [email protected] starts the server. Headless Chrome launches automatically for URL scans. Supports WCAG 2.0 A/AA/AAA and WCAG 2.1 tag filtering. The check_color_contrast tool works without a browser — pure computation against axe's contrast algorithm. The test_html_string tool tests raw HTML without needing a live URL.
Recipe: WCAG Accessibility Testing via a11y-mcp-server
Server: [email protected] (npx) Engine: axe-core 4.11.4 + Puppeteer (headless Chrome) Transport: stdio Auth: none required Tools: 6 — test_accessibility, test_html_string, get_rules, check_color_contrast, check_aria_attributes, check_orientation_lock
Spawn & handshake
npx -y [email protected]Server identifies as axe-accessibility-server v0.1.0. Send initialize → notifications/initialized → tools/list → tools/call.
Tool 1: checkcolorcontrast
Pure computation — no browser launch. Checks if a foreground/background color pair meets WCAG AA and AAA contrast requirements.
Input: {"foreground": "#777777", "background": "#ffffff", "fontSize": 14, "isBold": false} Output: contrastRatio: 4.5, passesWCAG2AA: true, passesWCAG2AAA: false, plus normalized hex/rgb values, large-text determination, and required ratios for both levels.
Accepts #hex, rgb(), and hsv() color formats.
Tool 2: test_accessibility
Full WCAG scan on a live URL via headless Chrome + Axe-core. Tags filter which WCAG level to test (wcag2a, wcag2aa, wcag21a, etc.).
Input: {"url": "https://example.com", "tags": ["wcag2aa"]} Output: violations: [], passes: 2, incomplete: 0, inapplicable: 1, plus test engine metadata (axe-core 4.11.4), user agent, viewport dimensions.
Observations
- Server cold-start: ~5s (npx install + headless Chrome bootstrap)
- Color contrast check: instant (no browser needed)
- Full URL scan: ~4s for example.com (simple page)
test_html_stringaccepts raw HTML — useful for testing components in isolation without deployingget_rulesreturns the full axe-core rule catalog, filterable by tags- example.com passes WCAG 2 AA with 0 violations
{ "server": "[email protected]", "transport": "stdio", "spawn": "npx -y [email protected]", "engine": "[email protected]", "handshake": { "initialize": { "protocolVersion": "2024-11-05", "clientInfo": { "name": "pathfinder", "version": "1.0.0" } }, "serverInfo": { "name": "axe-accessibility-server", "version": "0.1.0" }, "tools_count": 6 }, "tools_list": ["test_accessibility", "test_html_string", "get_rules", "check_color_contrast", "check_aria_attributes", "check_orientation_lock"], "call_1": { "tool": "check_color_contrast", "input": { "foreground": "#777777", "background": "#ffffff", "fontSize": 14, "isBold": false }, "output": { "originalInput": { "foreground": "#777777", "background": "#ffffff" }, "normalizedColors": { "foregroundHex": "#777777", "backgroundHex": "#ffffff", "foregroundRgb": "rgb(119, 119, 119)", "backgroundRgb": "rgb(255, 255, 255)" }, "fontSize": 14, "isBold": false, "contrastRatio": 4.5, "isLargeText": false, "passesWCAG2AA": true, "requiredRatioForAA": 4.5, "passesWCAG2AAA": false, "requiredRatioForAAA": 7, "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast" }, "isError": false }, "call_2": { "tool": "test_accessibility", "input": { "url": "https://example.com", "tags": ["wcag2aa"] }, "output": { "violations": [], "passes": 2, "incomplete": 0, "inapplicable": 1, "timestamp": "2026-06-11T16:19:36.176Z", "url": "https://example.com/", "testEngine": { "name": "axe-core", "version": "4.11.4" }, "testEnvironment": { "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/100.0.4889.0 Safari/537.36", "windowWidth": 1280, "windowHeight": 800 } }, "isError": false } }