The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Wcag Accessibility listing page.
A WCAG accessibility testing MCP for AI agents, Codex, Claude Code, and automated UI audits.
WCAG Accessibility MCP gives AI coding and design agents a real accessibility feedback loop. It renders web interfaces in Chromium, runs axe-core, checks color contrast, maps findings to WCAG guidance, and returns structured evidence that an agent can use to fix accessibility issues before a UI is treated as complete.
It is designed for people building with AI: product designers, design engineers, frontend developers, AI product teams, and anyone using agents to generate or review web interfaces.
This is an automated testing aid, not a WCAG certification service. It catches many common failures, but full accessibility review still requires human testing for keyboard behavior, focus order, screen readers, zoom, motion, content quality, and assistive-technology behavior.
AI-generated interfaces often look polished but fail basic accessibility checks: weak contrast, missing labels, broken semantic structure, poor ARIA usage, inaccessible forms, and hidden keyboard issues.
This MCP helps agents stop guessing. Instead of saying “follow WCAG,” it gives them testable feedback:
| Tool | What it does |
|---|---|
audit_url | Audits a rendered web page URL |
audit_html | Audits supplied HTML before it is hosted |
audit_file | Audits a local .html or .htm file inside an allowed project root |
audit_matrix | Experimental: audits one target across named viewports and groups findings by stable fingerprints |
compare_audits | Experimental: compares baseline and candidate audit results without rerunning the browser |
browser_diagnostics | Experimental: reports browser selection and setup guidance without launching Chromium |
inspect_screenshot | Experimental: captures screenshot evidence and optionally runs local OCR |
inspect_design_snapshot | Experimental: inspects exported Figma, Claude Design, or generic design-node data before implementation |
check_contrast | Calculates WCAG contrast for a foreground/background color pair |
suggest_contrast_fix | Suggests a passing color adjustment |
explain_issue | Explains an accessibility rule and how to fix it |
get_wcag_checklist | Returns the complete WCAG checklist with automated/manual coverage |
The server supports these profiles:
wcag2awcag2aawcag2aaawcag21aawcag21aaawcag22aawcag22aaabest-practiceAA profiles include Level A and AA criteria. AAA profiles include Level A, AA, and AAA criteria.
The default profile is wcag22aa.
For WCAG 2.2:
An automated axe mapping means partial automated coverage. It does not mean the whole WCAG success criterion has been fully tested.
Requirements:
Install from npm:
Or run directly:
If the server starts correctly, you should see:
Add the MCP server:
Check that it is connected:
Test prompt:
Expected result:
Open the Claude desktop config file on Windows:
Add this inside mcpServers:
If you already have another MCP server, keep it and add wcag-accessibility as a second entry.
Then fully quit Claude Desktop and reopen it.
Add the MCP server:
Test prompt:
Clone the repository:
Install dependencies:
Build:
Run tests:
Run browser integration and end-to-end tests:
npm test is the deterministic browser-free unit suite. Use npm run test:browser when the machine has a working Chrome, Edge, Chromium, or bundled browser setup.
The CLI can write JSON, Markdown, or SARIF reports and compare a baseline:
Start the stdio MCP server:
Start the optional HTTP transport:
The local HTTP endpoint is:
Health check:
All environment variables are optional for normal local use.
| Variable | Default | Purpose |
|---|---|---|
A11Y_MCP_BROWSER_PATH | Auto-detected | Absolute path to Chrome, Chromium, or Edge |
A11Y_MCP_ALLOWED_ROOT | Current working directory | Restricts local file audits to a specific folder |
A11Y_MCP_ALLOW_PRIVATE | true on stdio, false on HTTP | Allows localhost/private-network URL audits in trusted environments |
A11Y_MCP_ENABLE_FILE_AUDIT | false on HTTP | Enables local file audits over HTTP in trusted deployments |
A11Y_MCP_BROWSER_CONCURRENCY | 2 | Maximum concurrent Chromium audits |
A11Y_MCP_AUDIT_TIMEOUT_MS | 25000 | Timeout for the audit phase |
A11Y_MCP_NO_SANDBOX | false | Disables Chromium sandboxing only when the runtime requires it |
A11Y_MCP_OCR_COMMAND | tesseract | Local OCR executable used by inspect_screenshot when runOcr is true |
A11Y_MCP_ENABLE_EXPERIMENTAL_TOOLS | false | Advertises the in-progress matrix, screenshot, diagnostics, and design-snapshot tools |
A11Y_MCP_ALLOW_LOCAL_FILE_SUBRESOURCES | false | Allows local file audits to load file-based images/stylesheets beneath the allowed root |
HOST / A11Y_MCP_HOST | 127.0.0.1 | HTTP bind address |
A11Y_MCP_ALLOWED_HOSTS | Localhost names | Allowed Host headers for HTTP mode |
A11Y_MCP_BODY_LIMIT | 4mb | HTTP JSON body limit |
PORT | 3000 | HTTP transport port |
The stdio server is meant to run locally with the same permissions as the agent using it.
The HTTP transport is a deployment building block, not a public hosted service by itself. Do not expose it directly to the public internet without authentication, TLS, rate limits, request-size limits, outbound network controls, and a low-privilege runtime.
By default:
io.github.aditya-ariosity/wcag-accessibilityThe stable release currently audits rendered web interfaces and HTML. The evidence core reports criterion-level coverage and keeps unresolved manual requirements visible.
The stable release does not yet inspect:
Matrix, screenshot/OCR, and design-snapshot modules are experimental and require A11Y_MCP_ENABLE_EXPERIMENTAL_TOOLS=true. Direct Figma plugin inspection, persistence, automatic fixes, and deeper design-tool adapters remain future work.
MIT