# MCP Accessibility Checker

A Model Context Protocol (MCP) server for automated WCAG accessibility auditing of websites using Playwright and axe-core. Designed for AI coding agents and assistants to discover, diagnose, and guide fixes for accessibility issues.

## Use Cases for AI Agents

- **Accessibility Auditing**: Run full WCAG 2.1 AA audits on any URL
- **Targeted Checks**: Inspect specific categories (contrast, ARIA, forms, images, etc.)
- **Element-Level Inspection**: Drill into individual components by CSS selector
- **Report Generation**: Create markdown reports with executive summaries and fix guidance
- **Pair with [mcp-color-convert](https://github.com/bennyzen/mcp-color-convert)**: Use contrast audit results alongside color tools for complete accessibility remediation

## Installation & Configuration

### MCP Client Configuration

Add to your MCP client config (Claude Desktop, Gemini CLI, etc.):

```json
{
  "mcpServers": {
    "accessibility-checker": {
      "command": "npx",
      "args": ["-y", "mcp-accessibility-checker@latest"]
    }
  }
}
```

### Local Development

```bash
git clone https://github.com/bennyzen/mcp-accessibility-checker.git
cd mcp-accessibility-checker
npm install
npx playwright install chromium
npm run dev
```

## Available Tools (10)

### Full Audit

| Tool | Description |
|------|-------------|
| `audit` | Run all WCAG rules against a URL. Returns violations, passes, and incomplete checks. |

### Category Tools

| Tool | Description |
|------|-------------|
| `audit_aria` | ARIA roles, attributes, states, and name/role/value compliance |
| `audit_contrast` | Color contrast ratios and visual cues (WCAG AA/AAA) |
| `audit_forms` | Form labels, fieldsets, error identification |
| `audit_images` | Image alt text, roles, and text alternatives |
| `audit_structure` | Heading hierarchy, landmarks, document structure, semantics |
| `audit_navigation` | Keyboard accessibility, tab order, skip links, focus management |
| `audit_tables` | Table headers, scope, captions, data table structure |

### Element-Level

| Tool | Description |
|------|-------------|
| `check_element` | Run checks scoped to a specific CSS selector |

### Reporting

| Tool | Description |
|------|-------------|
| `report` | Generate a markdown report from audit results |

## Example Usage

### Full audit

```json
{
  "name": "audit",
  "arguments": { "url": "https://example.com" }
}
```

Returns structured JSON with all violations, including element selectors, HTML snippets, severity, and fix guidance.

### Category audit

```json
{
  "name": "audit_contrast",
  "arguments": { "url": "https://example.com" }
}
```

### Element check

```json
{
  "name": "check_element",
  "arguments": {
    "url": "https://example.com",
    "selector": "#login-form"
  }
}
```

### Generate report

```json
{
  "name": "report",
  "arguments": {
    "audit_json": "<JSON output from any audit tool>"
  }
}
```

Produces a markdown report:

```markdown
# Accessibility Audit Report

**URL:** https://example.com
**Date:** 2026-03-19T14:18:54.037Z
**Standard:** WCAG 2.1 Level AA

## Summary

| Severity | Count |
|----------|-------|
| Critical | 0     |
| Serious  | 0     |
| Moderate | 2     |

| Category   | Violations |
|------------|-----------|
| Structure  | 1         |
| Navigation | 1         |

## Moderate Issues

### landmark-one-main (1 element)
Ensure the document has a main landmark
[Rule documentation](...)

- `html`
  **Fix:** Document does not have a main landmark

## Passed Checks (13)
aria-hidden-body, bypass, color-contrast, ...
```

## Audit Result Shape

All audit tools return the same JSON structure:

```typescript
{
  url: string,
  timestamp: string,
  toolVersion: string,
  axeVersion: string,
  summary: {
    violations: number,
    passes: number,
    incomplete: number,
    bySeverity: { critical, serious, moderate, minor }
  },
  violations: [{
    id: string,          // axe rule ID
    severity: string,    // "critical" | "serious" | "moderate" | "minor"
    description: string,
    helpUrl: string,     // Deque rule documentation
    category: string,    // "aria" | "contrast" | "forms" | etc.
    nodes: [{
      selector: string,  // CSS selector path
      html: string,      // HTML snippet
      failureSummary: string
    }]
  }],
  passes: [{ id, description, nodes: number }],
  incomplete: [{ id, description, nodes: [{ selector, html }] }]
}
```

## Workflow: Full Accessibility Remediation

1. Run `audit` to get the full picture
2. Use category tools (`audit_contrast`, `audit_forms`, etc.) to drill into specific areas
3. Use `check_element` to inspect individual components
4. Use `report` to generate a markdown summary for stakeholders
5. Use [mcp-color-convert](https://github.com/bennyzen/mcp-color-convert) `compare` and `contrast` tools to find compliant color alternatives

## Troubleshooting

### Chromium not found
```bash
npx playwright install chromium
```

### Timeout on slow pages
The default navigation timeout is 30 seconds. For slow pages, consider auditing after the page is likely cached.

### No violations found
A clean audit doesn't mean the site is fully accessible. axe-core catches ~57% of WCAG issues automatically. Manual testing (keyboard navigation, screen reader) is still needed.

## License

MIT