# accessibility-mcp-server

**MCP-Server for Web Accessibility Checks (WCAG 2.1/2.2)**

Gives AI agents the ability to check websites for accessibility issues, validate ARIA attributes, check color contrast ratios, and generate full accessibility reports — without any API key.

[![PyPI version](https://badge.fury.io/py/accessibility-mcp-server.svg)](https://pypi.org/project/accessibility-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

## Features

- **WCAG 2.1 AA Compliance Checks** — Automated checks for 10+ WCAG success criteria
- **Color Contrast Analyzer** — Calculates contrast ratios and WCAG AA/AAA pass/fail
- **ARIA Validator** — Checks ARIA roles and attributes for correctness
- **Heading Structure Analyzer** — Validates heading hierarchy (H1→H2→H3...)
- **Image Alt Text Checker** — Finds images missing alt attributes
- **Form Label Validator** — Ensures all form inputs have accessible labels
- **Full A11y Report** — Comprehensive report with accessibility score (0-100)
- **WCAG Rule Reference** — Browse all WCAG 2.1 A/AA/AAA rules
- **No API Key Required** — Works with any public website

## Tools

| Tool | Description |
|------|-------------|
| `check_url_accessibility` | Full WCAG 2.1 AA check for any URL |
| `check_color_contrast` | Calculate contrast ratio between two colors |
| `validate_aria` | Validate ARIA attributes in HTML snippet |
| `check_heading_structure` | Analyze heading hierarchy on a page |
| `check_images_alt` | Check all images for alt text |
| `check_form_labels` | Check all form inputs for labels |
| `generate_a11y_report` | Comprehensive accessibility report with score |
| `list_wcag_rules` | List all WCAG 2.1 rules for a given level |

## Installation

```bash
pip install accessibility-mcp-server
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "accessibility": {
      "command": "accessibility-mcp-server"
    }
  }
}
```

## Example Prompts

- *"Check https://example.com for accessibility issues"*
- *"What is the contrast ratio between #333333 and #ffffff?"*
- *"Generate a full accessibility report for https://mysite.com"*
- *"Check if the images on https://example.com have alt text"*
- *"Validate the ARIA in this HTML: `<div role='buttn'>Click</div>`"*
- *"List all WCAG 2.1 AA rules"*

## WCAG Criteria Checked

| Criterion | Level | Check |
|-----------|-------|-------|
| 1.1.1 Non-text Content | A | Images without alt text |
| 1.3.1 Info and Relationships | A | Heading hierarchy, landmark regions |
| 1.4.3 Contrast (Minimum) | AA | Color contrast ratio calculator |
| 2.4.1 Bypass Blocks | A | Skip links and landmarks |
| 2.4.2 Page Titled | A | Missing or empty page titles |
| 2.4.4 Link Purpose | A | Generic link text detection |
| 3.1.1 Language of Page | A | Missing lang attribute |
| 3.3.2 Labels or Instructions | A | Form inputs without labels |
| 4.1.1 Parsing | A | Duplicate IDs |
| 4.1.2 Name, Role, Value | A | ARIA validation, unlabeled buttons |

## Tech Stack

- **Python 3.10+** with FastMCP
- **httpx** for async HTTP requests
- **BeautifulSoup4 + lxml** for HTML parsing
- WCAG formulas implemented directly (relative luminance, contrast ratio)

## License

MIT — Free for personal and commercial use.

---

*Built by [AiAgentKarl](https://github.com/AiAgentKarl) | Part of the AI Agent Tools ecosystem*