Accessibility MCP Server

An MCP (Model Context Protocol) server that provides accessibility auditing tools for LLMs through Cursor. Integrates axe-core (via Playwright), Lighthouse CLI, and optional WAVE API to deliver deterministic, machine-actionable accessibility audit results.

Features

• axe-core Integration: Automated accessibility testing via Playwright with full WCAG 2.1/2.2 coverage

• Lighthouse CLI: Comprehensive accessibility audits with performance insights

• WAVE API: Optional integration for additional accessibility validation

• Deterministic Output: All results normalised to explicit pass/fail/unknown outcomes

• WCAG Compliance: Every finding mapped to WCAG 2.1/2.2 criteria with severity classification

• Machine-Actionable: Results include selectors and DOM context for remediation

• Type-Safe: Full TypeScript implementation with strict type checking

Installation

Configuration

Create a .env file in the project root (see .env.example for template):

Usage

As MCP Server in Cursor

1. Build the project: npm run build

2. Configure in Cursor's MCP settings (~/.cursor/mcp.json or Cursor settings):

3. Restart Cursor to load the MCP server

Available MCP Tools

axe_audit

Run an accessibility audit using axe-core via Playwright. Supports URLs, local file paths, and localhost URLs.

Parameters:

• url (required): The URL to audit. Can be:

  • HTTP/HTTPS URL: "https://example.com" or "http://localhost:3000"

  • Local file path: "./index.html" or "/path/to/file.html"

  • File protocol URL: "file:///path/to/file.html"

• options (optional): Configuration object

  • tags: Array of WCAG tags (e.g., ["wcag2a", "wcag2aa"])

  • rules: Object with rule-specific configuration

  • timeout: Timeout in milliseconds (default: 30000)

  • browser: Browser to use - "chromium", "firefox", or "webkit" (default: "chromium")

Examples:

lighthouse_audit

Run an accessibility audit using Lighthouse CLI. Supports URLs, local file paths, and localhost URLs.

Parameters:

• url (required): The URL to audit. Can be:

  • HTTP/HTTPS URL: "https://example.com" or "http://localhost:3000"

  • Local file path: "./index.html" or "/path/to/file.html"

  • File protocol URL: "file:///path/to/file.html"

• categories (optional): Array of Lighthouse categories to include

• options (optional): Configuration object

  • onlyCategories: Array of categories to include

  • skipAudits: Array of audit IDs to skip

  • timeout: Timeout in milliseconds (default: 60000)

Examples:

wave_audit

Run an accessibility audit using WAVE API (requires API key). Supports URLs and localhost URLs. Local files are automatically served via a temporary local server.

Parameters:

• url (required): The URL to audit. Can be:

  • HTTP/HTTPS URL: "https://example.com" or "http://localhost:3000"

  • Local file path: "./index.html" (will be served via temporary server)

• apiKey (optional): WAVE API key (uses WAVE_API_KEY env var if not provided)

Examples:

Note: For local files, the MCP server automatically creates a temporary HTTP server to serve the file, as WAVE API requires HTTP/HTTPS URLs.

Output Format

All tools return normalised results in the following format:

Development

Prerequisites

• Node.js 18.0.0 or higher

• npm or yarn

Scripts

Project Structure

Architecture

The server follows a clean architecture pattern:

1. Tools Layer (src/tools/): MCP tool definitions that expose audit capabilities

2. Services Layer (src/services/): Business logic for audit execution and result normalisation

3. Adapters Layer (src/adapters/): Interface layer for external tools (axe, Lighthouse, WAVE)

4. Types Layer (src/types/): Shared type definitions for audit results and normalised outputs

Adding a New Audit Tool

See .cursor/commands/add-new-audit-tool.md for detailed instructions on adding a new accessibility audit tool.

Testing

CI/CD Integration

The project includes commands for CI/CD integration. See .cursor/commands/ci-gate-accessibility.md for details on setting up accessibility gates in your CI pipeline.

Contributing

1. Follow the architectural constraints defined in .cursor/rules/

2. Ensure all code passes type checking: npm run type-check

3. Write tests for new features

4. Ensure deterministic outputs (see .cursor/rules/determinism.md)

5. Map all findings to WCAG criteria (see .cursor/rules/accessibility.md)

License

MIT

Acknowledgments

• axe-core - Accessibility testing engine

• Lighthouse - Web performance and accessibility auditing

• WAVE - Web accessibility evaluation tool

• Playwright - Browser automation framework

• Model Context Protocol - Protocol for LLM tool integration