Skip to main content
Get started with AccessibilityHub in just a few minutes. This guide will have you analyzing web pages for accessibility issues through your AI assistant.

​
Installation

AccessibilityHub can be run without installation using npx, or installed globally for faster startup. 
npm install -g accessibility-hub
The npx approach (no installation) is recommended for MCP client configurations as it ensures you always use the latest version.

​
Configure Your MCP Client

Choose your MCP client and add AccessibilityHub to its configuration:
Add to your Claude Desktop configuration file:Configuration file location:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"]
    }
  }
}
After editing the config file, restart Claude Desktop.
On first run, Puppeteer will download Chrome/Chromium automatically. This may take a few minutes.

​
Verify Installation

After configuring your MCP client:
1

Restart your MCP client

Completely restart Claude Desktop, Cursor, Windsurf, or your CLI client.
2

Check available tools

Ask your AI assistant: “What accessibility tools are available?”You should see tools like analyze-with-axe, analyze-with-pa11y, analyze-contrast, analyze-with-lighthouse, and analyze-mixed.
3

Run your first analysis

Try: “Analyze the accessibility of https://example.com”

​
Your First Analysis

Let’s run a quick accessibility check: 
Analyze the accessibility of https://example.com

​
Understanding Results

AccessibilityHub returns enriched results with human context: 
{
  "ruleId": "image-alt",
  "severity": "serious",
  "wcag": {
    "criterion": "1.1.1",
    "level": "A",
    "principle": "perceivable"
  },
  "message": "Images must have alternate text",
  "humanContext": "**Non-text content (WCAG 1.1.1 - Level A)**...",
  "affectedUsers": ["screen-reader", "low-vision"],
  "priority": "critical",
  "remediationEffort": "low",
  "suggestedActions": [
    "Add descriptive alt attribute to images",
    "Use aria-label for decorative icons with function"
  ]
}

​
Key Fields

  • severity - critical, serious, moderate, or minor
  • wcag - Which WCAG criterion is violated
  • affectedUsers - Who experiences this barrier (screen-reader, keyboard-only, low-vision, etc.)
  • priority - Suggested fix priority based on user impact
  • remediationEffort - Estimated effort: low, medium, or high
  • suggestedActions - Step-by-step fixes

​
Common Use Cases

Quick Page Audit

Analyze https://my-site.com with all tools
Uses analyze-mixed to run axe-core and Pa11y in parallel with deduplication.

Pre-Deploy Check

Use the pre-deploy-check prompt for
https://staging.my-app.com
Get a GO/NO-GO decision with blocking issues highlighted.

Color Contrast Review

Check the contrast of https://my-site.com
with WCAG AAA level
Get detailed contrast ratios with suggested color fixes.

Lighthouse Score

What's the Lighthouse accessibility
score and how can I improve it?
Get a 0-100 score with prioritized improvement recommendations.

​
Using Pre-Built Prompts

AccessibilityHub includes prompt templates for common workflows: 
Use the full-accessibility-audit prompt with:
- url: https://example.com
- wcagLevel: AA

​
Troubleshooting

  • Ensure Node.js ≥ 20 is installed: node --version
  • Check that npx can find the package: npx -y accessibility-hub --help
  • Verify JSON syntax in your MCP client config file
  • Check client logs for detailed error messages
  • On first run, Puppeteer downloads Chrome (may take a few minutes)
  • On Linux servers, install dependencies: 
    apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libxcomposite1 libxrandr2
  • If behind a proxy, set PUPPETEER_SKIP_DOWNLOAD=true and install Chrome manually
  • Completely restart your MCP client (not just reload)
  • Check the server is listed in your client’s MCP servers list
  • Look for connection errors in client logs
  • Try asking explicitly: “List all available MCP tools”
  • First run is slower due to Chrome download
  • Complex pages take longer to analyze (2-5 seconds typical)
  • Using analyze-mixed runs multiple tools in parallel
  • For faster results, use single tools like analyze-with-axe

​
Next Steps

Accessibility Testing Concepts

Learn about the tools and methodologies

Effective Prompts

Tips for writing better accessibility prompts

Workflows Guide

Recommended workflows for common tasks

Interpreting Results

How to prioritize and act on findings

Build docs developers (and LLMs) love

Get started for freeTalk to us