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

# Clone the repository
git clone <repository-url>
cd accessibility-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Install Playwright browsers (required for axe-core)
npx playwright install chromium

Configuration

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

# WAVE API Configuration (optional)
WAVE_API_KEY=your_wave_api_key_here
WAVE_API_URL=https://wave.webaim.org/api/request

# Lighthouse Configuration (optional)
LIGHTHOUSE_TIMEOUT=60000
LIGHTHOUSE_CHROME_FLAGS=--headless --no-sandbox

# Playwright Configuration (optional)
PLAYWRIGHT_BROWSER=chromium
PLAYWRIGHT_TIMEOUT=30000

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

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

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:

{
  "name": "axe_audit",
  "arguments": {
    "url": "https://example.com",
    "options": {
      "tags": ["wcag2a", "wcag2aa"],
      "browser": "chromium"
    }
  }
}

{
  "name": "axe_audit",
  "arguments": {
    "url": "./src/index.html"
  }
}

{
  "name": "axe_audit",
  "arguments": {
    "url": "http://localhost:3000"
  }
}

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:

{
  "name": "lighthouse_audit",
  "arguments": {
    "url": "https://example.com",
    "categories": ["accessibility"]
  }
}

{
  "name": "lighthouse_audit",
  "arguments": {
    "url": "./dist/index.html"
  }
}

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:

{
  "name": "wave_audit",
  "arguments": {
    "url": "https://example.com",
    "apiKey": "your_api_key"
  }
}

{
  "name": "wave_audit",
  "arguments": {
    "url": "./src/index.html"
  }
}

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:

{
  url: string;
  tool: 'axe' | 'lighthouse' | 'wave';
  timestamp: string;
  results: Array<{
    rule_id: string;
    wcag_ref: string[];
    severity: 'critical' | 'serious' | 'moderate' | 'minor';
    confidence: 'high' | 'medium' | 'low';
    outcome: 'pass' | 'fail' | 'unknown';
    selector: string;
    dom_context: string;
    message: string;
    reason_code?: string; // Required when outcome is 'unknown'
  }>;
  summary: {
    total: number;
    pass: number;
    fail: number;
    unknown: number;
    by_severity: {
      critical: number;
      serious: number;
      moderate: number;
      minor: number;
    };
  };
}

Development

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Scripts

# Development mode (with hot reload)
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Type check without building
npm run type-check

# Lint code
npm run lint

Project Structure

accessibility-mcp/
├── .cursor/
│   ├── rules/          # Cursor behavioural constraints
│   └── commands/       # Cursor repeatable actions
├── src/
│   ├── adapters/       # External tool adapters (axe, Lighthouse, WAVE)
│   ├── services/       # Business logic (audits, normalisation)
│   ├── tools/          # MCP tool definitions
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions (WCAG mappings, selectors)
│   ├── index.ts        # Entry point
│   └── server.ts       # MCP server setup
├── tests/
│   ├── fixtures/       # Test data fixtures
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
└── dist/               # Compiled JavaScript output

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

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test tests/unit/normaliser.test.ts

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