a11y-toolkit — the accessibility layer for AI coding agents

12 MCP tools + 5 prompts + a skill that give any AI agent (Claude, Cursor, Windsurf, Codex…) the full WCAG 2.2 loop: audit → fix → document → watch. Zero dependencies at its core; every finding ships with a concrete remediation your agent can apply.

Accessibility is not optional anymore: the European Accessibility Act is in force since June 2025, ADA suits keep landing, and AI agents now write most of the web. This toolkit makes "is it accessible?" a one-question ask — and "then fix it" a one-command job.

What no other a11y tool gives an agent

The tools (10)

Prompts (slash-commands in supporting clients): audit-page (full audit workflow + what automation can't check), fix-contrast, pre-deploy-check (audit + diff → GO/NO-GO), declaration-eaa (collects legal fields, generates).

Install

Claude Code (one command):

claude mcp add a11y-toolkit -- uvx --from a11y-toolkit a11y-toolkit-mcp

Any MCP client with JSON config (Claude Desktop, Cursor, Windsurf, VS Code…):

{
  "mcpServers": {
    "a11y-toolkit": {
      "command": "uvx",
      "args": ["--from", "a11y-toolkit", "a11y-toolkit-mcp"],
      "timeoutMs": 60000
    }
  }
}

Or from the repo without publishing:

{ "mcpServers": { "a11y-toolkit": {
    "command": "uvx", "args": ["--from", "git+https://github.com/kinti/a11y-toolkit", "a11y-toolkit-mcp"] } } }

The rendered audit, snapshots and diffs use Playwright if present (pip install playwright && playwright install chromium); everything else works with zero dependencies.

The skill (teaches your agent when/how to use all of this)

git clone https://github.com/kinti/a11y-toolkit && cd a11y-toolkit
./skill/install-skill.sh     # → ~/.zcode/skills and ~/.claude/skills

CLI — same engine, one command

a11y pair "#1f2328" "#fbfaf7"                     # contrast, per-criterion verdicts
a11y image hero.jpg --text "#ffffff" --region 120,40,420,90
a11y audit --url https://example.com --lang en    # express static audit
a11y declaration --entidad "Acme" --url https://acme.example \
       --estado parcial --marco eaa --lang en --output decl.html
a11y snapshot https://mysite --out before.json    # before deploy (needs Playwright)
a11y diff before.json after.json                  # after deploy

Run from a clone with python3 a11y.py <subcommand>; from PyPI with uvx --from a11y-toolkit a11y ….

Watch it continuously (the deployment gate)

a11y audit --url https://mysite --pages 5 > audit.json        # light crawl
python3 -m a11ybudget --init < audit.json > budget.json       # accept today's baseline
a11y budget --budget budget.json --audit audit.json           # only NEW findings block (exit 2)
a11y sarif --from-audit audit.json -o a11y.sarif              # GitHub code scanning format

examples/a11y-watch.yml turns this into a weekly scheduled check that fails on regressions and publishes the SARIF to code scanning.

Honesty, built in

Automation covers ~1/3 of WCAG — every audit says so. The audit-page prompt and the bundled skill then have the agent check what it can (keyboard operability, focus visibility, zoom reflow, announced errors) using the manual checklist, and recommend a screen-reader pass for the rest. A filter, not a verdict.

Security & scope

A local tool: runs on your machine as your user. path (image) and output_path (statement) read/write local paths — use it in MCP clients you trust. Nothing leaves your machine except the URL you explicitly audit.

Development

python3 test_contrast.py && python3 test_audit.py && python3 test_dom.py && python3 test_mcp.py

test_dom.py self-skips without Playwright. Releases: tag vX.Y.Z → CI publishes to PyPI (trusted publishing); server.json is the official MCP Registry manifest. Listed on Smithery too. Contributions welcome — see CONTRIBUTING.md (the golden rules: zero dependencies at the core, es/en strings everywhere, honest scope notes).

Roadmap

• Rendered audit (computed contrast, target size 2.5.8, focus indicator)
• 0-100 weighted score · ARIA validity · criterion explanations
• Computed accessibility tree in snapshots + tree diff
• SARIF export → findings as GitHub code-scanning / PR annotations (a11y sarif)
• Honest dated badge as accessible SVG (a11y_badge)
• Accessibility error budget: only NEW findings block (a11y budget + examples/a11y-watch.yml)
• Multi-page same-domain crawl with aggregated scores (pages parameter)
• Scheduled surveillance recipe (weekly audit + budget gate as a GitHub Action)
• WCAG-EM conformance ladder (conformance-wcagem prompt + guided protocol)
• Same-origin iframes in the rendered audit + :focus/:hover state contrast

Author

Jesús Quintana Fernández (jquin.net) — SEO/GEO consultant and web-accessibility practitioner since 2003. MIT © 2026.