a11y-expert-mcp

A11y Expert MCP

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.

💬 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)

License

MIT

Author

Elli (@Elizabeth1979)