Color Converter

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: 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.):

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

Local Development

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

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

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

Category audit

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

Element check

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

Generate report

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

Produces a markdown report:

# 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:

{
  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 compare and contrast tools to find compliant color alternatives

Troubleshooting

Chromium not found

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