MCP Accessibility Audit Server

A comprehensive Model Context Protocol (MCP) server for website accessibility auditing using industry-standard tools like axe-core and Puppeteer. This server enables AI assistants to evaluate websites for WCAG compliance and provide detailed accessibility reports.

Features

• Comprehensive Accessibility Audits: Full WCAG 2.1 compliance checking (A, AA, AAA levels)
• Specialized Checks:
  • Color contrast analysis
  • Image accessibility (alt text, decorative vs informative)
  • Keyboard navigation testing
• Batch Processing: Audit multiple pages at once
• Detailed Reports: Human-readable markdown reports with prioritized issues and remediation guidance
• Industry Standards: Built on axe-core (used by Microsoft, Google) and Puppeteer

Installation

Prerequisites

• Node.js 18 or higher
• Chrome/Chromium browser installed on your system

Option 1: Install from npm (Recommended)

Global installation:

npm install -g @joshteravest/mcp-accessibility-audit-server

Local installation:

npm install @joshteravest/mcp-accessibility-audit-server

Using npx (no installation needed):

npx @joshteravest/mcp-accessibility-audit-server

Option 2: Install from Source

git clone https://github.com/JoshTerAvest/a11y-mcp.git
cd a11y-mcp
npm install
npm run build

Configuration

Add this server to your MCP settings file:

Claude Desktop

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

If installed globally via npm:

{
  "mcpServers": {
    "accessibility-audit": {
      "command": "mcp-accessibility-audit"
    }
  }
}

If installed via npx:

{
  "mcpServers": {
    "accessibility-audit": {
      "command": "npx",
      "args": ["@joshteravest/mcp-accessibility-audit-server"]
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "accessibility-audit": {
      "command": "node",
      "args": ["/absolute/path/to/a11y-mcp/build/index.js"]
    }
  }
}

Cline / Other MCP Clients

Same configuration as above - use the appropriate command based on your installation method.

Available Tools

1. audit_page

Run a comprehensive accessibility scan on a webpage.

Parameters:

• url (string, required): The URL of the webpage to audit
• wcag_level (string, optional): WCAG conformance level - 'A', 'AA', or 'AAA' (default: 'AA')

Example:

Please audit https://example.com for WCAG AA compliance

Returns:

• Violations categorized by severity (critical, serious, moderate, minor)
• Passes and incomplete checks
• Summary statistics
• Raw axe-core results

2. check_contrast

Analyze color contrast issues on a webpage.

Parameters:

• url (string, required): The URL of the webpage to analyze

Example:

Check the color contrast on https://example.com

Returns:

• All text/background combinations that fail WCAG contrast requirements
• Contrast ratios and required ratios
• Element selectors for each issue

3. check_images

Check images for accessibility issues.

Parameters:

• url (string, required): The URL of the webpage to check

Example:

Check all images on https://example.com for accessibility issues

Returns:

• Images missing alt text
• Images with potentially incorrect alt text usage
• Recommendations for decorative vs informative images

4. check_keyboard_navigation

Test keyboard navigation on a webpage.

Parameters:

• url (string, required): The URL of the webpage to test

Example:

Test keyboard navigation on https://example.com

Returns:

• Tab order issues
• Keyboard traps
• Missing focus indicators
• Problematic tabindex usage

5. batch_audit

Scan multiple pages and aggregate results.

Parameters:

• urls (array of strings, required): Array of URLs to audit
• wcag_level (string, optional): WCAG conformance level (default: 'AA')

Example:

Audit these pages: https://example.com, https://example.com/about, https://example.com/contact

Returns:

• Individual audit results for each URL
• Aggregated statistics
• Pages ranked by number of issues

6. generate_accessibility_report

Generate a detailed markdown report from audit results.

Parameters:

• results (object, required): Results from audit_page or batch_audit

Example:

Generate a detailed report from the previous audit results

Returns:

• Comprehensive markdown report
• Issues prioritized by severity
• Remediation guidance
• Code examples

Usage Examples

Example 1: Single Page Audit

User: "Can you check if communityactionnapavalley.org meets accessibility standards?"

Claude (using MCP):

I'll run an accessibility audit on that site.

[calls audit_page('https://communityactionnapavalley.org', 'AA')]

I found 23 accessibility issues:

Critical Issues (5):

• Missing alt text on 3 images (WCAG 1.1.1)
• Color contrast failures on navigation links (WCAG 1.4.3)
• Form inputs missing labels (WCAG 3.3.2)

Serious Issues (12):

• Heading levels skip from h1 to h3 (WCAG 1.3.1)
• Missing ARIA landmarks for main regions ...

Would you like detailed remediation steps for these issues?

Example 2: Batch Site Audit

User: "Audit all the main pages of my website"

Claude:

[calls batch_audit(['https://example.com', 'https://example.com/about', 'https://example.com/services', 'https://example.com/contact'])]

I've completed the audit of 4 pages:

Executive Summary:

• Total Issues: 47
• Most problematic page: /services (18 issues)
• Common issues across all pages: missing alt text, heading structure

[calls generate_accessibility_report(results)]

Here's your detailed report...

Example 3: Specific Check

User: "Check if the images on my homepage have proper alt text"

Claude:

[calls check_images('https://example.com')]

I found 5 image accessibility issues:

Critical (3):

1. Hero image missing alt attribute
2. Logo missing alt text
3. Team photo without description

Warnings (2):

1. Decorative border image should have role="presentation"
2. Chart image has very long alt text (consider aria-describedby)

Development

Project Structure

a11y-mcp/
├── src/
│   ├── index.ts                    # Main MCP server
│   ├── accessibility-auditor.ts    # Core audit functionality
│   └── report-generator.ts         # Report generation
├── build/                          # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run watch

Technical Details

Technology Stack

• MCP SDK: @modelcontextprotocol/sdk for MCP server implementation
• axe-core: Industry-standard accessibility testing engine
• Puppeteer: Headless Chrome for running tests in real browser
• TypeScript: Type-safe implementation

WCAG Compliance

This tool tests for:

• WCAG 2.1 Level A: Basic accessibility features
• WCAG 2.1 Level AA: Enhanced accessibility (recommended standard)
• WCAG 2.1 Level AAA: Highest level of accessibility

Limitations

• Automated Testing: This tool provides automated testing, which catches ~30-40% of accessibility issues
• Manual Testing Required: Human testing is still needed for:
  • Screen reader compatibility
  • Actual keyboard navigation flow
  • Content clarity and readability
  • Context-specific accessibility concerns
• JavaScript Required: Requires pages to have JavaScript enabled
• Browser Dependency: Requires Chrome/Chromium to be installed

Interview Preparation Tips

Key Points to Discuss

1. Why MCP?

   • Enables AI assistants to perform accessibility audits automatically
   • Provides structured, consistent results
   • Can be integrated into development workflows

2. Why axe-core?

   • Industry standard (used by Microsoft, Google, government sites)
   • Comprehensive WCAG coverage
   • Actively maintained and updated
   • Free and open source

3. Architecture Decisions

   • Separation of concerns (auditor, reporter, server)
   • Reusable browser instance for efficiency
   • Comprehensive error handling
   • Extensible design for adding new tools

4. Future Enhancements

   • PDF report generation
   • Historical tracking of audit results
   • Integration with CI/CD pipelines
   • Custom rule definitions
   • Screenshot capture of violations
   • Accessibility score calculation

Demo Script

1. Show a simple audit of a public website
2. Demonstrate contrast checking
3. Run a batch audit on multiple pages
4. Generate a comprehensive report
5. Discuss remediation strategies

Resources

• WCAG 2.1 Guidelines
• axe-core Documentation
• MCP Documentation
• WebAIM Resources
• A11y Project

License

MIT

Contributing

This is a proof of concept for interview preparation. Contributions and suggestions are welcome!

Troubleshooting

Puppeteer Browser Not Found

If you see errors about Chrome not being found:

# Install Chrome/Chromium on your system
# Ubuntu/Debian
sudo apt-get install chromium-browser

# MacOS
brew install chromium

# Or set custom Chrome path
export PUPPETEER_EXECUTABLE_PATH=/path/to/chrome

Timeout Errors

If pages take too long to load:

• The default timeout is 30 seconds
• Check your internet connection
• Try auditing the page manually to confirm it loads

Memory Issues

For batch audits of many pages:

• Process URLs in smaller batches
• The browser instance is reused but can consume memory
• Restart the MCP server if needed

Contact

For questions or feedback about this project, please open an issue on GitHub.