mcp-accessibility-scanner

The MCP Accessibility Scanner provides automated web accessibility testing and browser automation powered by Playwright and Axe-core. It exposes a suite of tools that let you navigate web pages, run WCAG conformance checks, capture annotated snapshots, generate accessibility reports, and manage persistent browser sessions. Core capabilities include a comprehensive scan_page tool for detailed accessibility analysis, audit_site to crawl and aggregate violations across a site, and scan_page_matrix to compare multiple viewport and state variants. You can also perform keyboard focus audits with audit_keyboard, and control navigation and interactions through browser_navigate, browser_navigate_back, browser_navigate_forward, and a range of interaction tools like browser_snapshot, browser_click, browser_type, browser_hover, browser_drag, and browser_select_option. These tools enable LLMs to reason about accessibility issues, collect remediation guidance, and produce ready-to-share reports with visual context.

Prerequisites:

• Node.js and npm installed on your system
• Access to a terminal or shell with internet connectivity
• Optional: Docker if you prefer containerized usage

Install (global):

1. Install the MCP Accessibility Scanner globally via npm:

npm install -g mcp-accessibility-scanner

Docker option: 2) Pull the pre-built Docker image:

docker pull justasmonkev/mcp-accessibility-scanner

3. Run with Docker (example):

docker run -i --rm justasmonkev/mcp-accessibility-scanner

VS Code / CLI integration: 4) If you use Claude Desktop integration, you can add the MCP as shown in the README config example:

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

Build from source (advanced): 5) Clone the repository and install dependencies, then build/run as directed by the project documentation.

Notes:

• The npm package name is mcp-accessibility-scanner.
• If you choose to use Docker, ensure you mount an output directory if you want to persist reports or screenshots outside the container.

Tips and common considerations:

• Use the scan_page tool with violationsTag to filter for WCAG levels and categories relevant to your accessibility goals.
• For site-wide assessment, the audit_site tool helps aggregate violations across multiple pages; configure maxPages and maxDepth to control crawl scope.
• scan_page_matrix compares variants (e.g., baseline, mobile, desktop, reduced-motion) and produces a per-variant delta report; review the generated scan-matrix-{timestamp}.json file for insights.
• audit_keyboard helps verify focus behavior and can produce screenshots when issues are detected via screenshotOnIssue.
• When running in headless environments, tune Playwright timeouts (timeouts.navigationTimeout and timeouts.defaultTimeout) to avoid premature terminations on slower pages.
• If running via Docker, consider mounting a host directory to /app/output to preserve reports and screenshots after container exit.