A11y Feedback MCP

Give coding and design agents a real accessibility feedback loop instead of another reminder to “follow WCAG.”

a11y-feedback-mcp renders an interface in Chromium, runs axe-core, and returns actionable evidence to any Model Context Protocol client: violated rules, impact, CSS selectors, DOM snippets, computed styles, bounding boxes, remediation steps, and mathematically passing contrast candidates.

It works directly with Codex and Claude Code. For Claude Design, the reliable workflow is to connect Claude Code to both Claude Design's MCP server and this server, then audit the generated HTML or live preview and send corrections back through the design workflow.

This is an automated testing aid, not a WCAG certification service. It deliberately reports incomplete checks and requires human testing for keyboard, focus, screen readers, zoom, motion, cognition, and content quality.

What “live feedback” means

flowchart TD
    A["Agent creates or changes UI"] --> B["Render at target viewport"]
    B --> C["Run axe + contrast analysis"]
    C --> D["Return evidence and correction"]
    D --> E["Agent proposes or applies code fix"]
    E --> F["Re-run same audit"]
    F --> G["Human checks incomplete behavior"]

The server is read-only. It never silently edits a project. The connected agent uses the evidence to make a scoped change, then reruns the audit to verify it.

Tools

Tool	Purpose
`audit_url`	Audit a rendered public or local development URL
`audit_html`	Audit generated HTML before it is hosted
`audit_file`	Audit a local `.html`/`.htm` file inside an allowed project root
`check_contrast`	Calculate WCAG contrast for a color pair and text style
`suggest_contrast_fix`	Propose the smallest black/white-directed color adjustment that passes
`explain_issue`	Turn an axe rule ID into implementation and verification guidance
`get_wcag_checklist`	Return the complete A/AA/AAA criterion set with W3C links and automated/manual coverage

All tools are annotated read-only. The server also exposes an accessibility-fix-loop prompt.

Standards profiles

The audit tools support wcag2a, wcag2aa, wcag2aaa, wcag21aa, wcag21aaa, wcag22aa, wcag22aaa, and best-practice. AA profiles include all required A and AA criteria; AAA profiles include A, AA, and AAA. wcag22aa remains the default because W3C recommends the latest WCAG version and cautions against requiring whole-site AAA as a general policy. Use AAA as an explicit enhanced target and report criterion-level progress.

An axe mapping means partial automated coverage, never that the complete success criterion was tested. get_wcag_checklist exposes all 55 criteria required for WCAG 2.2 AA or all 86 required for WCAG 2.2 AAA, including the manual work automation cannot complete.

Requirements

Node.js 20 or newer
Chrome or Edge recommended
Windows, macOS, or Linux

The server looks for installed Chrome/Edge first. On supported Linux environments it can fall back to the bundled @sparticuz/chromium. You can set A11Y_MCP_BROWSER_PATH to an explicit browser executable. Chromium sandboxing stays enabled by default; set A11Y_MCP_NO_SANDBOX=true only for constrained containers or Lambda-style runtimes that cannot launch Chrome otherwise.

Install on Windows

Open PowerShell in the folder where you keep projects:

git clone https://github.com/aditya-ariosity/a11y-feedback-mcp.git
cd a11y-feedback-mcp
npm install
npm run build

If the repository is not on GitHub yet, download or copy this folder first, then run the final three commands inside it.

Connect Codex

From PowerShell, use the absolute path to the built entry point:

codex mcp add a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

Or add the equivalent configuration to ~/.codex/config.toml:

[mcp_servers.a11y_feedback]
command = "node"
args = ["C:\\full\\path\\to\\a11y-feedback-mcp\\dist\\index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 90

[mcp_servers.a11y_feedback.env]
A11Y_MCP_ALLOWED_ROOT = "C:\\full\\path\\to\\your-projects"

Restart Codex, then ask:

Audit this page at 1440×900 and 390×844. Fix critical and serious issues, rerun both audits, and list the remaining manual checks.

See docs/codex.md for verification and troubleshooting.

Connect Claude Code

claude mcp add --scope user a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

Run claude mcp list to confirm the connection. See docs/claude-code-and-design.md for the Claude Design bridge workflow.

Development

npm install
npm run check
npm test
npm run test:e2e
npm run build

npm test covers color math, network protection, remediation, and the MCP contract. npm run test:e2e launches Chromium and audits the intentionally inaccessible fixture.

Start the local stdio server:

npm run dev

Start the optional Streamable HTTP transport:

npm run build
npm run start:http

The endpoint is http://127.0.0.1:3000/mcp; health is http://127.0.0.1:3000/health. HTTP binds to 127.0.0.1 by default.

Environment variables

Variable	Default	Meaning
`A11Y_MCP_BROWSER_PATH`	Auto-detected	Absolute Chrome/Chromium/Edge executable path
`A11Y_MCP_ALLOWED_ROOT`	Server working directory	Only local HTML under this root can be audited
`A11Y_MCP_ALLOW_PRIVATE`	`true` on stdio, `false` on HTTP	Allow localhost/private-network URL targets
`A11Y_MCP_ENABLE_FILE_AUDIT`	`false` on HTTP	Permit local-file audit through HTTP after root restriction
`A11Y_MCP_BROWSER_CONCURRENCY`	`2`	Maximum concurrent Chromium audits
`A11Y_MCP_AUDIT_TIMEOUT_MS`	`25000`	Deadline for the axe audit phase
`A11Y_MCP_NO_SANDBOX`	`false`	Launch Chromium without its sandbox only when the runtime requires it
`HOST` / `A11Y_MCP_HOST`	`127.0.0.1`	HTTP bind address
`A11Y_MCP_ALLOWED_HOSTS`	Localhost names	Comma-separated Host headers accepted by HTTP mode
`A11Y_MCP_BODY_LIMIT`	`4mb`	HTTP JSON body limit; must stay above the `audit_html` schema limit
`PORT`	`3000`	HTTP transport port

Do not expose the reference HTTP server directly to the public internet. Put authentication, TLS, rate limits, request-size limits, and tenant isolation in front of it. Read docs/security.md.

Current scope

The MVP covers rendered web UIs and deterministic contrast calculations. It does not yet inspect native mobile apps, PDFs, canvases, video captions, or raw Claude Design pixels. Planned adapters can add framework-aware patches, screenshot/OCR assistance, design-token integration, CI annotations, and first-class design-canvas connectors without changing the MCP contract.

Project documents

License

MIT

wcag-accessibility-mcp

Install to Claude Code

README