README.md
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: 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
- Run
auditto get the full picture - Use category tools (
audit_contrast,audit_forms, etc.) to drill into specific areas - Use
check_elementto inspect individual components - Use
reportto generate a markdown summary for stakeholders - Use mcp-color-convert
compareandcontrasttools to find compliant color alternatives
Troubleshooting
Chromium not found
npx playwright install chromium
Timeout on slow pages
The de
Tools 10
auditRun all WCAG rules against a URL.audit_ariaCheck ARIA roles, attributes, states, and compliance.audit_contrastCheck color contrast ratios and visual cues.audit_formsCheck form labels, fieldsets, and error identification.audit_imagesCheck image alt text and text alternatives.audit_structureCheck heading hierarchy, landmarks, and document structure.audit_navigationCheck keyboard accessibility, tab order, and focus management.audit_tablesCheck table headers, scope, and data structure.check_elementRun accessibility checks scoped to a specific CSS selector.reportGenerate a markdown report from audit results.Try it
→Run a full WCAG 2.1 AA accessibility audit on https://example.com and summarize the critical issues.
→Check the login form at https://example.com/login for accessibility issues using the check_element tool.
→Audit the navigation menu on my website for keyboard accessibility and tab order compliance.
→Generate a markdown report based on the recent audit results for the homepage.
→Identify any missing alt text or image accessibility issues on the landing page.