Accessibility MCP — WCAG 2.2 AA (GOV.UK standard)

A Model Context Protocol server that audits web pages and sites for WCAG 2.2 level AA accessibility, aligned with the GOV.UK / GDS standard that UK public sector bodies are legally required to meet (since 1 October 2024).

It drives a real headless Chromium (via Playwright) and runs up to four independent accessibility engines — axe-core, pa11y (HTML_CodeSniffer + axe), Lighthouse and IBM Equal Access — layers GOV.UK-specific checks and remediation guidance on top, and returns results as structured JSON, a human-readable Markdown report, and a GDS-style compliance summary.

It can drive interactive journeys (navigate, click, fill, log in) and audit the resulting state. Optimized for efficiency with 41 streamlined tools instead of 168 individual rule tools.

Honest by design. Automated testing detects only ~30–40% of WCAG issues. Every report separates automated failures, needs manual review, and passed checks, and any unverified AA criterion keeps the status at "partially compliant". This tool is a starting point for, not a replacement for, a full manual audit.

Tools

Bundled audits (multi-engine):

Dedicated single-engine audits (take url, html or session_id):

Interactive navigation (stateful browser session):

Automated checks & rule-specific audits:

Grouped audit tools: run related rules at once.

Catalogue / reporting:

Each audit tool returns:

• json — structured, machine-readable results (violations, severity, WCAG criteria, affected selectors, remediation);

• markdown_report — a human-readable report grouped by severity;

• gds_summary — a GOV.UK-flavoured compliant / partially compliant / not compliant summary with reasons;

• audit_id — pass it to generate_accessibility_statement to reuse the result.

Related MCP server: Accessibility MCP Server

Recent Optimizations

🎯 Ponytail Performance Improvements (v0.2):

• Tool count: 168 → 41 tools (-76% reduction)

• Interface: Replaced 100+ per-rule tools with single axe_check_rule(rule_id)

• Performance: Simplified configuration, faster server startup

• Functionality: All accessibility testing engines preserved

• Code quality: Removed 200+ lines of unnecessary complexity

Engines

Choose engines per call via engines=["axe","pa11y","lighthouse","ibm"] (default ["axe"]). Findings from every engine are normalised to a common shape with WCAG criteria and labelled by source, so you can cross-check results.

axe runs in-process; the other three run in a Node subprocess (accessibility_mcp/engines_node/). If the Node runner is not installed, those engines report a clear "not installed" error and axe still works.

What it checks

• Full axe-core WCAG 2.2 rule set — 105 rules covering contrast, alt text, labels, names, landmarks, etc.

• pa11y / Lighthouse / IBM — independent rulesets for cross-checking.

• GOV.UK custom checks — accessibility-statement link presence, "Skip to main content" skip link, a single <main> landmark, and GOV.UK Design System usage.

• WCAG 2.2 awareness — flags the criteria new in 2.2 (2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8) and marks non-automatable criteria as needs manual review rather than silently passing them.

Installation

python -m venv .venv && source .venv/bin/activate
pip install -e .
# Chromium: this server reuses an existing Playwright Chromium if present
# (see configuration), otherwise install one:
playwright install chromium

# Optional — pa11y, Lighthouse and IBM engines (needs Node.js):
bash accessibility_mcp/engines_node/setup.sh

axe-core is vendored in accessibility_mcp/vendor/axe.min.js — no CDN needed. The axe rule catalogue (vendor/axe-rules.json) contains 105 rules for axe_check_rule.

The Node engines reuse the same Chromium as axe (no extra browser download). Only axe is required; the others are optional and degrade gracefully if absent.

Running

# Run directly over stdio:
accessibility-mcp
# or
python -m accessibility_mcp.server

Register with an MCP client

Add to your client config (e.g. Claude Desktop claude_desktop_config.json, or the example mcp.json in this repo):

{
  "mcpServers": {
    "accessibility": {
      "command": "accessibility-mcp"
    }
  }
}

If you installed into a virtualenv, point command at that venv's executable, e.g. /path/to/.venv/bin/accessibility-mcp.

Configuration (environment variables)

Chromium auto-detection. MCP clients spawn the server with a sanitised environment (typically just HOME/PATH/SHELL/TERM), so PLAYWRIGHT_BROWSERS_PATH is usually stripped before the server starts. When it is absent, the server still probes well-known default install locations (/opt/pw-browsers, ~/.cache/ms-playwright) so audits work out of the box. Set ACCESSIBILITY_MCP_CHROMIUM to override discovery explicitly. | ACCESSIBILITY_MCP_PROXY / HTTPS_PROXY | none | Outbound proxy for audit_url / audit_site. | | ACCESSIBILITY_MCP_PAGE_TIMEOUT_MS | 30000 | Page load timeout. | | ACCESSIBILITY_MCP_MAX_PAGES | 20 | Default crawl page limit. | | ACCESSIBILITY_MCP_MAX_DEPTH | 2 | Default crawl depth limit. |

audit_url / audit_site need outbound network access to the target site. In locked-down environments behind an egress policy, set HTTPS_PROXY (Chromium is pointed at it automatically); audit_html needs no network.

Development

pip install -e ".[dev]"
pytest                 # unit + browser-backed integration tests (local fixtures)

The integration tests drive a real headless Chromium against the HTML fixtures in tests/fixtures/, so they require a working Chromium but no network access.

Architecture

accessibility_mcp/
  server.py            FastMCP entry point — 41 optimized tools
  audit.py             Orchestration (URL / HTML / site / single rule / open page)
  config.py            WCAG tags, engines, browser/proxy discovery, limits
  engine/              browser.py, axe_runner.py, crawler.py, node_bridge.py, session.py
  engines_node/        Node runner for pa11y / Lighthouse / IBM (runner.mjs, setup.sh)
  rules/               wcag22.py, govuk_checks.py, remediation.py, normalize.py, axe_rules.py
  reporting/           models.py, builder.py, json/markdown/gds renderers
  vendor/              axe.min.js, axe-rules.json (105 axe rules)
scripts/generate_axe_rules.py   Regenerate vendor/axe-rules.json from axe-core

Disclaimer

This server helps identify accessibility problems and draft an accessibility statement. It does not, on its own, establish legal compliance. A full manual audit (keyboard operation, screen-reader testing, focus order, captions, etc.) is required to claim conformance with WCAG 2.2 AA.