A11y Expert MCP

[!IMPORTANT] Archived. Superseded by accessibility-evidence-engine. Its pattern lookup lives on there as the explain tool of @aee/mcp, which reads the patterns from a11y-skills, their one source. This repository is read-only and kept for its history.

An accessibility expert for your AI coding assistant. This MCP (Model Context Protocol) server gives AI tools like Claude, Cursor, and Windsurf real-time access to WAI-ARIA patterns, code review, contrast checking, and WCAG guidance — so the code they write is accessible from the start.

What's Inside

🔧 Tools

📚 Knowledge Base (33 Components)

Every pattern comes from the WAI-ARIA Authoring Practices and includes roles, states, properties, keyboard interaction, and code examples.

Canonical source: The 33 pattern instruction files in this server are synced from a11y-skills, the community-maintained source of truth. If you want to contribute a new pattern or improve an existing one, open the PR there.

💬 Prompts

Pre-built workflows your AI assistant can use:

📖 Resources

Browsable knowledge base for MCP clients:

• `a11y://patterns` — Index of all 33 component patterns
• `a11y://patterns/{component}` — Full pattern detail for any component

Installation

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Option 1: Run directly with uvx (no install needed)

uvx a11y-expert-mcp

Option 2: Install with pip

pip install a11y-expert-mcp

Then run:

a11y-expert-mcp

Option 3: Run from source

git clone https://github.com/Elizabeth1979/a11y-expert-mcp.git
cd a11y-expert-mcp
uv run a11y-expert-mcp

Configuration

Claude Desktop / Claude Code

Add to your MCP config (~/.claude/config.json or Claude Desktop settings):

{
  "mcpServers": {
    "a11y": {
      "command": "uvx",
      "args": ["a11y-expert-mcp"]
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "a11y": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/a11y-expert-mcp",
        "a11y-expert-mcp"
      ]
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Use the same command and args — check your editor's MCP configuration docs for the exact config file location.

Usage Examples

Once connected, your AI assistant can:

Get an accessible pattern:

"How do I build an accessible tabs component?" → The assistant calls get_pattern("tabs") and gets the full WAI-ARIA pattern with keyboard interaction and code.

Review code for issues:

"Check this modal for accessibility problems" → The assistant calls review_code(code, component_type="modal") and gets specific issues with fixes.

Check color contrast:

"Does #666 on #fff pass WCAG?" → The assistant calls check_contrast("#666", "#fff") and gets AA/AAA results for normal and large text.

Generate a WCAG checklist:

"Give me a WCAG AA checklist for my checkout page" → The assistant uses the wcag-checklist prompt to generate a tailored compliance checklist.

How It Works

The server bundles 33 WAI-ARIA pattern documents as a knowledge base. When your AI assistant asks about a component, it gets the real specification — not hallucinated ARIA attributes. The review_code tool runs 10+ static checks for common anti-patterns (click handlers on divs, missing labels, broken heading hierarchy, positive tabindex, etc.) and cross-references relevant patterns.

No external API calls. No database. Everything runs locally.

Tech Stack

• MCP SDK (FastMCP)
• Python 3.11+
• WAI-ARIA Authoring Practices knowledge base (bundled markdown files)

Related tools

Part of a broader accessibility engineering toolkit. Pair this with:

• [`screen-reader-cli`](https://github.com/Elizabeth1979/screen-reader-cli) — CLI for screen-reader-driven testing. Where a11y-expert-mcp gives your AI assistant static guidance (patterns, code review), screen-reader-cli runs live screen-reader checks against real pages using Virtual Screen Reader + Playwright. Static + runtime = full coverage.
• [`a11y-skills`](https://github.com/Elizabeth1979/a11y-skills) — Canonical source for the pattern instruction files this server serves.
• [`a11y-engineering-toolkit`](https://github.com/Elizabeth1979/a11y-engineering-toolkit) — Umbrella repo with browser-side audit panel + UX widget, plus the full portfolio map.

License

MIT

Author

Elli (@Elizabeth1979)