Accessibility MCP Server

A comprehensive Model Context Protocol (MCP) server for web accessibility testing and WCAG compliance analysis. This server provides automated accessibility testing capabilities for web pages, HTML snippets, and specific accessibility checks, designed to integrate seamlessly with MCP-compatible host applications.

🚀 Key Features

• 🌐 URL Testing: Test any public URL for accessibility issues using Puppeteer and axe-core
• 🕷️ Website-Wide Testing: Crawl and test entire websites for comprehensive accessibility audits
• 📝 HTML Snippet Testing: Analyze raw HTML strings for accessibility compliance
• 📋 Multi-Standard Support: Test against WCAG 2.0/2.1/2.2, Section 508, ADA, EN 301 549, and more using axe-core tags
• 🎯 Flexible Standard Combinations: Use presets (wcag-aa, ada, section508) or specify individual axe-core tags
• 🎨 Color Contrast Analysis: Check color combinations for WCAG contrast requirements
• ♿ ARIA Validation: Validate proper usage of ARIA attributes and roles
• 📱 Mobile Testing: Orientation lock detection and mobile accessibility issues
• 📊 Comprehensive Reports: Detailed accessibility reports with actionable recommendations
• 🔒 Local Execution: All testing happens locally - no external API calls or data transmission
• 🏗️ Enterprise Ready: Built for CI/CD integration and production environments

🔌 Integration with Host Applications

Supported MCP Host Applications

This server is compatible with any application that supports the Model Context Protocol (MCP), including:

• Claude Desktop - Anthropic's desktop application
• Cline VS Code Extension - Development environment integration
• Custom MCP Clients - Any application using the @modelcontextprotocol/sdk

Quick Integration Setup

For MCP Clients (like Claude Desktop, VS Code Extensions)

Add this configuration to your MCP client:

{
  "command": "npx",
  "args": ["-y", "accessibility-mcp-server"],
  "env": {
    "MCP_MODE": "true"
  }
}

For Local Development/Testing

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

Simple Mode (faster startup, core features only)

{
  "command": "npx",
  "args": ["-y", "accessibility-mcp-server", "--simple"],
  "env": {
    "MCP_MODE": "true"
  }
}

Note: The server will be published to NPM as accessibility-mcp-server for easy npx usage.

For Claude Desktop

1. Install the server:

npm install -g accessibility-mcp-server

2. Configure Claude Desktop by adding to your claude_desktop_config.json:

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

3. Restart Claude Desktop and the accessibility tools will be available.

For Cline VS Code Extension

1. Install the server globally:

npm install -g accessibility-mcp-server

2. Configure in VS Code settings or Cline configuration:

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

For Custom Applications

Install the package as a dependency:

npm install accessibility-mcp-server

Then integrate programmatically:

import { AccessibilityMCPServer } from 'accessibility-mcp-server';

// Create and start the server
const server = new AccessibilityMCPServer({
  mode: 'full', // or 'simple' for basic features only
  enableLogging: true
});

await server.run();

📦 Installation Options

1. NPM Package (Recommended for Host Integration)

# For global command-line usage
npm install -g accessibility-mcp-server

# For local project integration
npm install accessibility-mcp-server

2. From Source (Development)

# Clone the repository
git clone https://github.com/nigamutkarsh/accessibility-mcp-server.git
cd AccessibilityMCP

# Install dependencies
npm install

# Build the project
npm run build

# Install globally
npm install -g .

3. Docker Deployment

# Build Docker image
docker build -t accessibility-mcp .

# Run container
docker run -d --name accessibility-mcp \
  -p 3000:3000 \
  accessibility-mcp

� Multi-Standard Support

The server supports testing against multiple accessibility standards simultaneously:

Standard Presets

Quick presets for common standard combinations:

• wcag-a: WCAG 2.0/2.1/2.2 Level A
• wcag-aa: WCAG 2.0/2.1/2.2 Level AA (default)
• wcag-aaa: WCAG 2.0/2.1/2.2 Level AAA
• section508: Section 508 compliance tags
• ada: ADA Title III compliance (WCAG 2.1 AA + legal guidance)
• en301549: EN 301 549 European standard
• all-standards: Comprehensive testing across all standards

Individual Standard Tags

Specify individual axe-core tags for fine-grained control (~150+ available):

WCAG Tags:

• wcag2a, wcag2aa, wcag2aaa - WCAG 2.0 levels
• wcag21a, wcag21aa, wcag21aaa - WCAG 2.1 levels
• wcag22aa - WCAG 2.2 Level AA
• wcag111, wcag131, wcag143, wcag244, etc. - Specific success criteria

Other Standards:

• section508, section508.22.a, section508.22.g - Section 508
• EN-301-549 - European accessibility standard
• TTv5 - Trusted Tester v5
• RGAAv4 - French accessibility standard

Category Tags:

• cat.color, cat.forms, cat.keyboard, cat.aria, cat.text-alternatives
• cat.name-role-value, cat.semantics, cat.language, etc.

Standard Combination Logic

• AND Logic (default): Rules must match ALL specified standards (requireAll: true)
• OR Logic: Rules match ANY specified standard (requireAll: false)

Usage Examples

// Test against multiple presets
{
  "standardPresets": ["wcag-aa", "section508", "ada"]
}

// Test against specific tags with AND logic
{
  "standards": ["wcag21aa", "wcag244", "section508.22.a"],
  "requireAll": true
}

// Test against category tags with OR logic
{
  "standards": ["cat.color", "cat.forms"],
  "requireAll": false
}

�🛠️ Available MCP Tools

The server provides four main tools for accessibility testing, with two operational modes:

Simple Mode Tools (Basic Features)

• test_accessibility - Test URLs or HTML content
• test_website_accessibility - Test entire websites (crawl multiple pages)
• check_color_contrast - Validate color combinations

Full Mode Tools (All Features)

• test_accessibility - Test URLs or HTML content
• test_website_accessibility - Test entire websites (crawl multiple pages)
• check_color_contrast - Validate color combinations
• get_wcag_rules - Retrieve WCAG rule information

Tool Usage Examples

1. Test Accessibility

Test a website or HTML content for accessibility issues:

For URLs with standard presets:

{
  "name": "test_accessibility",
  "arguments": {
    "target": "https://example.com",
    "type": "url",
    "level": "basic",
    "standardPresets": ["wcag-aa", "section508"]
  }
}

For URLs with specific standard tags:

{
  "name": "test_accessibility",
  "arguments": {
    "target": "https://example.com",
    "type": "url",
    "level": "full",
    "standards": ["wcag21aa", "wcag244", "section508.22.a", "EN-301-549"]
  }
}

For HTML snippets (legacy wcagLevel still supported):

{
  "name": "test_accessibility",
  "arguments": {
    "target": "<button>Click me</button><div>Content without proper contrast</div>",
    "type": "html", 
    "level": "full",
    "wcagLevel": "AAA"
  }
}

For ADA compliance testing:

{
  "name": "test_accessibility",
  "arguments": {
    "target": "https://example.com",
    "type": "url",
    "level": "full",
    "standardPresets": ["ada"]
  }
}

2. Test Website Accessibility

Test entire websites by crawling multiple pages:

With standard presets:

{
  "name": "test_website_accessibility",
  "arguments": {
    "baseUrl": "https://example.com",
    "standardPresets": ["wcag-aa", "section508"],
    "maxPages": 20,
    "maxDepth": 3,
    "concurrency": 3,
    "excludePatterns": ["/admin/", "/api/", ".pdf"],
    "continueOnError": true,
    "delay": 1000
  }
}

With specific standard tags:

{
  "name": "test_website_accessibility",
  "arguments": {
    "baseUrl": "https://example.com",
    "standards": ["wcag21aa", "wcag244", "EN-301-549"],
    "maxPages": 10,
    "maxDepth": 2
  }
}

Legacy wcagLevel parameter (still supported):

{
  "name": "test_website_accessibility",
  "arguments": {
    "baseUrl": "https://example.com",
    "wcagLevel": "AA",
    "maxPages": 20,
    "maxDepth": 3
  }
}

Key Features of Website Testing:

• 🕷️ Automatic Crawling: Discovers pages by following links
• 📊 Site-wide Reports: Aggregated accessibility metrics across all pages
• 🎯 Configurable Scope: Control depth, page limits, and URL patterns
• ⚡ Parallel Testing: Test multiple pages simultaneously
• 🔍 Common Issues: Identifies violations that appear across multiple pages

📖 For detailed website testing documentation, see WEBSITE_TESTING.md

3. Check Color Contrast

Validate color combinations for WCAG compliance:

{
  "name": "check_color_contrast",
  "arguments": {
    "foreground": "#333333",
    "background": "#ffffff",
    "fontSize": 16,
    "isBold": false
  }
}

4. Get WCAG Rules (Full Mode Only)

Retrieve information about WCAG accessibility rules: Query rules by standard presets:

{
  "name": "get_wcag_rules",
  "arguments": {
    "standardPresets": ["wcag-aa", "section508"],
    "category": "color",
    "search": "contrast",
    "limit": 10
  }
}

Query rules by specific standard tags:

{
  "name": "get_wcag_rules",
  "arguments": {
    "standards": ["wcag21aa", "wcag244", "EN-301-549"],
    "requireAll": true,
    "limit": 20
  }
}

Legacy wcagLevel parameter (still supported):

{
  "name": "get_wcag_rules",
  "arguments": {
    "wcagLevel": "AA",
    "category": "color",
    "search": "contrast",
    "limit": 10
  }
}

🔧 MCP Client Integration

Using with @modelcontextprotocol/sdk

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

async function setupAccessibilityTesting() {
  // Create transport to the accessibility server
  const transport = new StdioClientTransport({
    command: 'accessibility-mcp',
    args: []
  });

  // Create MCP client
  const client = new Client({
    name: 'my-accessibility-client',
    version: '1.0.0'
  }, {
    capabilities: {}
  });

  // Connect to the server
  await client.connect(transport);

  // List available tools
  const tools = await client.listTools();
  console.log('Available tools:', tools);

  // Test a website
  const result = await client.callTool('test_accessibility', {
    target: 'https://example.com',
    type: 'url',
    level: 'basic',
    wcagLevel: 'AA'
  });

  console.log('Accessibility test result:', result);

  // Clean up
  await client.close();
}

setupAccessibilityTesting().catch(console.error);

Custom Host Application Integration

import { spawn } from 'child_process';
import { EventEmitter } from 'events';

class AccessibilityMCPClient extends EventEmitter {
  constructor() {
    super();
    this.process = null;
    this.requestId = 0;
  }

  async connect() {
    // Start the accessibility MCP server
    this.process = spawn('accessibility-mcp', [], {
      stdio: ['pipe', 'pipe', 'pipe']
    });

    // Handle server responses
    this.process.stdout.on('data', (data) => {
      const responses = data.toString().split('\n').filter(Boolean);
      responses.forEach(response => {
        try {
          const parsed = JSON.parse(response);
          this.emit('response', parsed);
        } catch (error) {
          console.error('Failed to parse response:', error);
        }
      });
    });

    // Initialize the connection
    await this.sendRequest('initialize', {
      protocolVersion: '1.0.0',
      capabilities: {},
      clientInfo: {
        name: 'custom-accessibility-client',
        version: '1.0.0'
      }
    });
  }

  async sendRequest(method, params = {}) {
    const request = {
      jsonrpc: '2.0',
      id: ++this.requestId,
      method,
      params
    };

    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => {
        reject(new Error('Request timeout'));
      }, 30000);

      const handler = (response) => {
        if (response.id === request.id) {
          clearTimeout(timeout);
          this.removeListener('response', handler);
          if (response.error) {
            reject(new Error(response.error.message));
          } else {
            resolve(response.result);
          }
        }
      };

      this.on('response', handler);
      this.process.stdin.write(JSON.stringify(request) + '\n');
    });
  }

  async testAccessibility(target, options = {}) {
    return this.sendRequest('tools/call', {
      name: 'test_accessibility',
      arguments: {
        target,
        type: options.type || 'url',
        level: options.level || 'basic',
        wcagLevel: options.wcagLevel || 'AA'
      }
    });
  }

  async checkColorContrast(foreground, background, options = {}) {
    return this.sendRequest('tools/call', {
      name: 'check_color_contrast', 
      arguments: {
        foreground,
        background,
        fontSize: options.fontSize || 16,
        isBold: options.isBold || false
      }
    });
  }

  async close() {
    if (this.process) {
      this.process.kill();
      this.process = null;
    }
  }
}

⚙️ Configuration & Environment

Server Modes

The server supports two operational modes:

Simple Mode:

• Basic accessibility testing
• Color contrast analysis
• Minimal resource usage
• Faster startup time

Full Mode (Default):

• Complete accessibility testing suite
• WCAG rules database access
• Advanced analysis features
• Comprehensive reporting

# Start in simple mode
accessibility-mcp --simple

# Start in full mode (default)
accessibility-mcp

Environment Variables

# Server mode configuration
ACCESSIBILITY_MCP_MODE=full   # or 'simple'

# Disable logging when running as MCP server
MCP_MODE=true

# Browser configuration
PUPPETEER_HEADLESS=true
PUPPETEER_TIMEOUT=30000

# Performance settings
NODE_ENV=production
LOG_LEVEL=error

Host Application Configuration

Different host applications require different configuration approaches:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "accessibility": {
      "command": "accessibility-mcp",
      "args": ["--simple"]
    }
  }
}

Cline/MCP Configuration:

{
  "mcpServers": {
    "accessibility-testing": {
      "command": "accessibility-mcp",
      "args": [],
      "env": {
        "ACCESSIBILITY_MCP_MODE": "full"
      }
    }
  }
}

📊 Response Format

All tools return responses in a consistent format:

interface ToolResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    type: string;
    message: string;
    details?: any;
  };
  processingTime: number;
  timestamp: string;
}

Sample Accessibility Test Response

{
  "success": true,
  "data": {
    "target": "https://example.com",
    "type": "url",
    "wcagLevel": "AA",
    "violations": [
      {
        "id": "color-contrast",
        "impact": "serious", 
        "description": "Elements must have sufficient color contrast",
        "help": "Ensure the contrast ratio is at least 4.5:1",
        "helpUrl": "https://dequeuniversity.com/rules/axe/4.8/color-contrast",
        "nodes": [
          {
            "html": "<p style=\"color: #999; background: #fff;\">Low contrast text</p>",
            "target": ["p"],
            "failureSummary": "Fix any of the following:\n  Element has insufficient color contrast"
          }
        ]
      }
    ],
    "summary": {
      "totalViolations": 1,
      "violationsByImpact": {
        "critical": 0,
        "serious": 1,
        "moderate": 0,
        "minor": 0
      },
      "compliance": {
        "A": false,
        "AA": false, 
        "AAA": false
      },
      "score": 75
    },
    "metadata": {
      "testDuration": 2500,
      "pageTitle": "Example Website",
      "viewport": { "width": 1920, "height": 1080 }
    }
  },
  "processingTime": 2500,
  "timestamp": "2024-12-01T10:30:00.000Z"
}

🚀 Production Deployment

Enterprise Environment Setup

1. Install as system service:

# Install globally
npm install -g accessibility-mcp-server

# Create systemd service (Linux)
sudo cat > /etc/systemd/system/accessibility-mcp.service << EOF
[Unit]
Description=Accessibility MCP Server
After=network.target

[Service]
Type=simple
User=accessibility
ExecStart=/usr/local/bin/accessibility-mcp
Restart=always
Environment=NODE_ENV=production
Environment=MCP_MODE=true

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable accessibility-mcp
sudo systemctl start accessibility-mcp

2. Docker Production Setup:

# Production Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY config/ ./config/
EXPOSE 3000
USER node
CMD ["node", "dist/index.js"]

3. CI/CD Integration:

# GitHub Actions example
name: Accessibility Testing
on: [push, pull_request]

jobs:
  accessibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install Accessibility MCP Server
        run: npm install -g accessibility-mcp-server
      
      - name: Test Website Accessibility
        run: |
          # Note: CLI interface would need to be implemented for CI/CD
          # This is a conceptual example
          echo "Accessibility testing would run here"

🔒 Security & Compliance

Security Features

• 🔒 Local Processing: All accessibility testing happens locally - no external API calls
• 🛡️ Input Validation: All inputs validated using Zod schemas
• 🧹 Resource Management: Automatic cleanup of browser instances and memory
• 📦 Sandboxed Execution: Puppeteer runs in sandboxed mode
• 🚫 No Data Transmission: Zero data leaves the customer environment

Privacy Compliance

• GDPR Compliant: No personal data processing or storage
• SOC 2 Ready: Designed for enterprise security requirements
• Zero Trust: No external dependencies or data transmission
• Audit Trail: Comprehensive logging for security auditing

🆘 Troubleshooting

Common Integration Issues

Issue: MCP server not starting

# Check if Node.js version is compatible
node --version  # Should be 18.0.0 or higher

# Verify installation
accessibility-mcp --version

# Check for conflicting processes
ps aux | grep accessibility-mcp

Issue: Tools not appearing in host application

# Verify MCP server is properly configured
cat ~/.config/claude-desktop/claude_desktop_config.json

# Test server manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | accessibility-mcp

Issue: Browser automation failures

# Install required dependencies (Linux)
sudo apt-get install -y chromium-browser

# Check browser permissions
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Performance Optimization

For high-volume testing:

# Set environment variables for better performance
export PUPPETEER_HEADLESS=true
export NODE_ENV=production
export ACCESSIBILITY_MCP_MODE=simple

Memory management:

# Monitor memory usage
top -p $(pgrep -f accessibility-mcp)

# Restart server if memory usage is high
sudo systemctl restart accessibility-mcp

📝 API Reference

Tool: test_accessibility

Tests websites or HTML content for accessibility violations.

Parameters:

• target (string, required): URL or HTML content to test
• type (enum): "url" | "html" (default: "url")
• level (enum): "basic" | "full" (default: "basic")
• wcagLevel (enum): "A" | "AA" | "AAA" (default: "AA")

Tool: check_color_contrast

Analyzes color combinations for WCAG compliance.

Parameters:

• foreground (string, required): Foreground color (hex, rgb, hsl, or named)
• background (string, required): Background color (hex, rgb, hsl, or named)
• fontSize (number): Font size in pixels (default: 16)
• isBold (boolean): Whether text is bold (default: false)

Tool: get_wcag_rules (Full Mode Only)

Retrieves WCAG accessibility rule information.

Parameters:

• wcagLevel (enum, optional): "A" | "AA" | "AAA"
• category (string, optional): Rule category filter
• search (string, optional): Search term for rules
• limit (number, optional): Maximum rules to return (1-50, default: 20)

📄 License

MIT License - see LICENSE file for details.

🤝 Support & Contributing

• Issues: GitHub Issues
• Documentation: Check the /docs folder for additional guides
• Contributing: Fork the repository and submit pull requests
• Discussions: Use GitHub Discussions for questions and feature requests

Built with ❤️ for web accessibility and inclusive design