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, and it exposes one tool per axe-core rule (~100) for fine-grained checks.

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-check tools (on by default): the machine-testable WCAG surface.

Each audit tool takes url, html or session_id. Disable per-criterion tools with ACCESSIBILITY_MCP_AUTOMATED_CHECK_TOOLS=0.

Grouped audit tools (on by default): run a related set of rules at once.

Each takes url, html or session_id. Disable with ACCESSIBILITY_MCP_GROUP_TOOLS=0.

Per-axe-rule tools (~100, on by default): one tool per axe rule, e.g. axe_color_contrast, axe_image_alt, axe_label. Each takes url, html or session_id. Disable with ACCESSIBILITY_MCP_PER_RULE_TOOLS=0.

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: Web Accessibility MCP Server

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 (wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa) — 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 per-rule tool catalogue (vendor/axe-rules.json) is generated by python scripts/generate_axe_rules.py (only needed when updating axe-core).

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)

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 — bundled + nav + ~100 per-rule tools
  audit.py             Orchestration (URL / HTML / site / single rule / open page)
  config.py            WCAG tags, engines, browser/proxy/node 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 (per-rule catalogue)
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.