MCP Accessibility Auditor 🔍

🎯 What is it?

MCP Accessibility Auditor is a powerful tool that brings professional web accessibility testing directly into your AI assistant (like Claude or Cursor). It scans websites and generates comprehensive reports showing accessibility issues based on WCAG 2.2 standards.

The Problem It Solves

Web accessibility is crucial but often overlooked. Traditional accessibility testing requires:

• Multiple tools and browser extensions
• Manual checking and documentation
• Technical knowledge to interpret results
• Time-consuming report generation

This tool solves all of that by integrating accessibility auditing directly into your AI workflow.

How It Works

1. You ask your AI assistant (in natural language):

"Scan https://mywebsite.com for accessibility issues"

2. The tool automatically:

• Opens the website in a headless browser
• Runs 50+ accessibility tests using industry-standard axe-core
• Analyzes against WCAG 2.2 Level AA standards
• Generates detailed reports (JSON + HTML)

3. You get back:

• ✅ Compliance score (0-100%)
• 📊 Issues prioritized by severity (Critical → Minor)
• 🎯 Exact elements that need fixing
• 💡 Step-by-step fix guidance with code examples
• 📚 WCAG criteria references
• ⏱️ Estimated fix time

Who Should Use This?

🎨 Frontend Developers - Test accessibility while developing, fix issues before production
🧪 QA Engineers - Automate accessibility testing, generate compliance reports
♿ Accessibility Specialists - Quick audits, client reports, prioritize remediation
👥 Product Teams - Ensure WCAG compliance, track accessibility metrics

✨ Features

✅ WCAG 2.2 Level AA Compliance Testing
✅ Prioritized Issue Reporting (Critical → Serious → Moderate → Minor)
✅ Fix-Ready Guidance with code examples for common violations
✅ Dual Format Reports (JSON + HTML)
✅ Compliance Score Calculation (0-100%)
✅ Effort Estimation for remediation
✅ Comprehensive Violation Details with affected elements
✅ Beautiful HTML Reports with embedded CSS

🚀 Quick Start

Option 1: Install via npm (Recommended)

npm install -g @sureshdotariya/mcp-accessibility-auditor

Option 2: Clone and Build

git clone https://github.com/sureshdotariya/mcp-accessibility-auditor.git
cd mcp-accessibility-auditor
npm install
npm run build

📋 Prerequisites

• Node.js 18+ (Required for modern JavaScript features)
• npm or yarn
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

⚙️ Configuration

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["mcp-accessibility-auditor"]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-accessibility-auditor/dist/index.js"]
    }
  }
}

For Cursor IDE

Add to MCP Tools settings in Cursor:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["mcp-accessibility-auditor"]
    }
  }
}

After configuration, restart your MCP client.

💬 Usage Examples

Example 1: Basic Scan

Prompt:

Scan https://google.com for accessibility issues

Output:

🔍 Accessibility Scan Complete - WCAG 2.2 Level AA

📊 SCAN SUMMARY:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
URL: https://google.com
Timestamp: 10/9/2025, 12:40:35 PM

📈 RESULTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Compliance Score: 90%
🔴 Total Issues: 3
⚠️  Critical/Serious: 2
⏱️  Estimated Fix Time: 1 hours

📋 BREAKDOWN BY SEVERITY:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 Critical: 2
🟠 Serious: 0
🟡 Moderate: 0
🟢 Minor: 1

✓ Passed Tests: 26
⚠ Incomplete Tests: 0

🔧 TOP PRIORITY FIXES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Certain ARIA roles must contain particular children
   WCAG: wcag2a, wcag131
   Priority: P1
   Quick Fix: Ensures elements with an ARIA role that require child roles contain them

2. ARIA attributes must conform to valid values
   WCAG: wcag2a, wcag412
   Priority: P1
   Quick Fix: Ensures all ARIA attributes have valid values

3. id attribute value must be unique
   WCAG: wcag2a, wcag411
   Priority: P4
   Quick Fix: Ensures every id attribute value is unique

📁 GENERATED REPORTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ ./reports/accessibility-report-google-com-2025-10-09.json
✓ ./reports/accessibility-report-google-com-2025-10-09.html

Example 2: Perfect Score Website

Prompt:

Check accessibility on https://company.com/login

Output:

🔍 Accessibility Scan Complete - WCAG 2.2 Level AA

📈 RESULTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Compliance Score: 96%
🔴 Total Issues: 1
⚠️  Critical/Serious: 1
⏱️  Estimated Fix Time: 1 hours

✅ No accessibility issues found! This page is WCAG 2.2 AA compliant.

Example 3: Get Session Statistics

Prompt:

Show me accessibility scan statistics

Output:

📊 Scan Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Scans Performed: 5
Session Started: 10/9/2025, 2:30:00 PM

🛠 Available Tools

scan_accessibility

Scan a URL for accessibility issues.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | url | string | ✅ Yes | - | The URL to scan (must include protocol) | | wcagLevel | string | No | AA | Compliance level: A, AA, or AAA | | outputFormat | string | No | both | Report format: json, html, or both | | saveToDisk | boolean | No | true | Save reports to ./reports directory |

Natural Language Examples:

• "Scan https://example.com for accessibility issues"
• "Check WCAG AAA compliance on https://mysite.com"
• "Audit https://app.example.com and give me JSON only"

get_scan_statistics

Get statistics about scans performed in the current session.

Natural Language Example:

• "Show me scan statistics"
• "How many pages have I scanned?"

📊 Output Formats

Console Output

Real-time summary with:

• ✅ Compliance score (0-100%)
• 🔴 Issue breakdown by severity
• 🔧 Top priority fixes with WCAG references
• ⏱️ Estimated fix time
• 📁 Report file locations

JSON Report

Structured data perfect for:

• CI/CD pipeline integration
• Custom reporting tools
• Automated tracking
• API integration

Sample structure:

{
  "result": {
    "url": "https://example.com",
    "timestamp": "2025-10-09T14:30:15.000Z",
    "violations": [...],
    "passes": 38,
    "violationCount": 12,
    "criticalCount": 2,
    "complianceScore": 72
  },
  "fixGuidance": [...],
  "summary": {
    "totalIssues": 12,
    "criticalIssues": 5,
    "estimatedEffort": "2-5 days"
  }
}

HTML Report

Beautiful, self-contained report with:

• 📊 Visual summary dashboard
• 🎨 Color-coded severity levels
• 📖 Expandable violation details
• 💡 Code examples for fixes
• 🔗 Direct links to WCAG documentation
• 📱 Responsive design

Open HTML reports:

# macOS/Linux
open reports/accessibility-report-*.html

# Windows
start reports/accessibility-report-*.html

🔍 What Gets Scanned

The scanner checks for 50+ common accessibility issues including:

🔴 Critical/Serious Issues

• Color contrast violations (WCAG 1.4.3)
• Missing form labels (WCAG 1.3.1, 3.3.2)
• Missing image alt text (WCAG 1.1.1)
• Buttons/links without accessible names (WCAG 4.1.2)
• Missing page language (WCAG 3.1.1)
• ARIA implementation errors (WCAG 4.1.2)

🟡 Moderate Issues

• Heading structure problems (WCAG 1.3.1)
• Landmark navigation issues (WCAG 2.4.1)
• Focus management problems (WCAG 2.4.7)
• Keyboard accessibility (WCAG 2.1.1)

🟢 Minor Issues

• Semantic HTML improvements
• Best practice recommendations
• Duplicate IDs (WCAG 4.1.1)

💡 Fix Guidance

Each violation includes comprehensive guidance:

• WCAG Criteria: Direct mapping to WCAG 2.2 success criteria
• Priority Level: P1 (Critical) → P4 (Minor)
• Common Causes: Why the issue occurs
• How to Fix: Step-by-step remediation instructions
• Code Examples: Before/after code snippets
• Learn More: Links to detailed documentation

Example Fix Guidance:

Color Contrast Insufficient
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 How to Fix:
• Ensure normal text has a contrast ratio of at least 4.5:1
• Ensure large text (18pt+) has a contrast ratio of at least 3:1
• Use tools like WebAIM Contrast Checker to verify colors

Code Example:
/* Before - Insufficient contrast */
.text { color: #999; background: #fff; }

/* After - Sufficient contrast */
.text { color: #595959; background: #fff; } /* 7:1 ratio */

🎯 Use Cases

Development Workflow

"Before I commit this PR, scan the feature preview at 
https://preview-pr-123.staging.company.com"

QA Testing

"Run accessibility scans on all main user flows:
1. /signup
2. /dashboard  
3. /checkout"

Compliance Audits

"Generate a comprehensive WCAG 2.2 AA audit report for 
https://company.com"

Competitor Analysis

"Compare accessibility between:
- Our site: https://oursite.com
- Competitor: https://competitor.com"

🏗️ Architecture

src/
├── index.ts          # MCP server implementation
├── scanner.ts        # Accessibility scanning engine (Puppeteer + axe-core)
├── reporter.ts       # Report generation (JSON + HTML)
├── guidance.ts       # Fix guidance database
└── types.ts          # TypeScript type definitions

🔧 Technical Details

Core Dependencies

• @modelcontextprotocol/sdk: MCP server implementation
• puppeteer: Headless browser automation
• axe-core: Industry-standard accessibility testing engine (Deque Systems)
• axe-puppeteer: Integration layer between Puppeteer and axe-core

Performance

• ⚡ Average scan time: 5-15 seconds per page
• 🔄 Handles dynamic content and SPAs
• 🛡️ Automatic retries and error handling
• 💾 Memory-efficient with proper cleanup

Compliance Standards

• ✅ WCAG 2.2 Level AA (default)
• ✅ WCAG 2.1 Level AA (backward compatible)
• ✅ WCAG 2.0 Level AA (backward compatible)
• ⚙️ Configurable for Level A or AAA testing

⚠️ Limitations

• Requires JavaScript execution (uses headless browser)
• Cannot scan password-protected pages without authentication setup
• Best for public websites and web applications
• Some manual testing may still be required for complete accessibility audits
• Cannot detect all accessibility issues (e.g., context-dependent problems)

🛠️ Development

# Watch mode for development
npm run watch

# Build for production
npm run build

# Run the server directly
npm start

# Run with development build
npm run dev

📦 Publishing

See NPM_PUBLISHING_GUIDE.md for detailed publishing instructions.

🗺️ Roadmap

• [ ] Authentication support for protected pages
• [ ] Batch scanning multiple URLs
• [ ] Custom rule configuration
• [ ] CI/CD integration examples
• [ ] PDF report generation
• [ ] Historical scan comparison
• [ ] Screenshot capture of violations
• [ ] Integration with popular issue trackers

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Areas for improvement:

• Additional fix guidance for more violation types
• Enhanced HTML report styling
• Support for more WCAG criteria
• Performance optimizations
• Additional language support

📝 License

MIT License - see LICENSE file for details.

🆘 Support & Resources

Getting Help

• 📖 Quick Start Guide
• 🐛 Report Issues
• 💬 Discussions

Accessibility Resources

• WCAG 2.2 Guidelines
• axe-core Rules
• WebAIM Resources
• A11y Project Checklist

MCP Resources

• Model Context Protocol Docs
• Claude Desktop
• MCP Servers Repository

🌟 Star History

If you find this tool helpful, please consider giving it a star on GitHub!

Built with ❤️ for accessible web experiences

Making the web accessible, one scan at a time.