temanuel1/a11y-mcp-server

A11y MCP Server

An MCP (Model Context Protocol) server that provides accessibility testing tools for AI code agents.

What does this do?

This MCP server gives AI assistants (like Claude, Cursor, etc.) the ability to:

• 🔍 Scan code for accessibility issues
• 🌐 Run Lighthouse audits on running apps
• 📝 Generate structured fix prompts

Directory Structure

a11y-mcp-server/
├── pyproject.toml           # Package definition
├── README.md                # This file
├── src/
│   └── a11y_mcp/
│       ├── __init__.py      # Makes this a Python package
│       ├── server.py        # MCP server implementation
│       └── tools.py         # A11y scanning functions
└── .env                     # Environment variables (optional)

Prerequisites

1. Node.js & npm (for ESLint and Lighthouse)
2. Python 3.10+
3. ESLint with jsx-a11y plugin in your target project

Installation

1. Create the directory structure:

mkdir -p src/a11y_mcp
touch src/a11y_mcp/__init__.py

2. Install the package:

# Install in development mode
pip install -e .

# Or install dependencies only
pip install mcp anthropic python-dotenv

3. Install Node dependencies (in your target project):

npm install --save-dev eslint eslint-plugin-jsx-a11y

4. Install Lighthouse (optional, for dynamic scanning):

npm install -g lighthouse

Using with Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "a11y": {
      "command": "python",
      "args": ["-m", "a11y_mcp.server"],
      "cwd": "/path/to/a11y-mcp-server"
    }
  }
}

Then restart Claude Desktop. You'll see a 🔨 icon indicating MCP tools are available!

Available Tools

1. scan_static_a11y

Scan code files for accessibility issues using ESLint.

Parameters:
- path: File or directory to scan

2. scan_dynamic_a11y

Run Lighthouse audit on a running app.

Parameters:
- url: URL to scan (e.g., http://localhost:3000)

3. get_all_a11y_issues

Get comprehensive report (static + dynamic).

Parameters:
- path: File/directory for static scan
- url: (optional) URL for dynamic scan

4. generate_fix_prompt

Generate structured prompt for fixing issues.

Parameters:
- issues: JSON string of issues
- file_path: File to fix

Example Usage

Once connected to Claude Desktop (or another MCP client):

You: "Scan my React components for accessibility issues"

Claude: [Uses scan_static_a11y tool on your src/components directory]

You: "Fix those issues"

Claude: [Uses generate_fix_prompt, then edits files using its code editing capabilities]

Development

Run the server directly for testing:

python -m a11y_mcp.server

Troubleshooting

"ESLint not found"

• Make sure you have ESLint installed in your target project
• Check that npx eslint works from command line

"Lighthouse not found"

• Install globally: npm install -g lighthouse
• Or use npx: npx lighthouse

"MCP server not showing up in Claude"

• Check your claude_desktop_config.json syntax
• Make sure the cwd path is correct
• Restart Claude Desktop
• Check logs in ~/Library/Logs/Claude/

Next Steps

• Add more sophisticated issue parsing
• Support for additional linters (axe-core, pa11y)
• Batch processing for large codebases
• Issue prioritization by severity