io.github.Bishop81/accessibility-scanner-mcp

accessibility-scanner-mcp

An MCP server that lets an AI agent scan a web page for WCAG accessibility issues and get back findings it can act on. The agent calls one tool with a URL; it gets every violation grouped by severity, each with the exact element selector, the offending HTML, the specific failure, the WCAG success criterion, and a fix-guide link — plus the items that still need human review.

It runs the real axe-core engine in your local Chrome (via playwright-core), so nothing about the pages you scan leaves your machine. It scrolls the page first so lazy-loaded content is actually checked rather than silently skipped, and it resolves color contrast over CSS gradients, which most tools leave as "needs review."

Upgrading from 0.1.x? 0.2.0 sees more of each page and returns more findings for the same URL. See CHANGELOG.md.

Part of accessibilityscanner.app.

Requirements

• Node.js 18+
• A Chromium-based browser: Chrome, Chromium or Edge, found automatically in that order. Set CHROME_PATH to point at a specific binary if you'd rather choose. A browser already installed by Playwright is used as a last resort; nothing is ever downloaded for you.

Or no browser at all

Set SCANNER_API_URL and the scan runs on accessibilityscanner.app instead of locally:

{ "env": { "SCANNER_API_URL": "https://accessibilityscanner.app" } }

No account or key needed — it uses the same public endpoints the website's own form uses. Useful in CI, in a container, or anywhere you can't install a browser. Hosted scans also carry suggested fix colours for contrast failures, which the local scanner doesn't compute yet.

⚠️ In this mode the URL you scan is sent to our server. The local path sends nothing anywhere, and stays the default — hosted mode is opt-in via that environment variable only.

Install

Add it to your MCP client's config. No global install needed — npx fetches it on first run.

Claude Desktop (claude_desktop_config.json), Cursor, Claude Code, or any MCP client:

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

If Chrome is not auto-detected, add an env block:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["-y", "accessibility-scanner-mcp"],
      "env": { "CHROME_PATH": "/usr/bin/google-chrome" }
    }
  }
}

The tool

scan_accessibility

Returns a report grouped by severity. For each rule: the WCAG criterion, a fix-guide link, and per element the selector, HTML, and exact failure. Example flow with an agent:

You: Audit https://example.com for accessibility and fix what you can. Agent: (calls scan_accessibility) → reads the findings → edits the code → re-scans.

Honest about limits

Automated testing covers the machine-checkable subset of WCAG (most of the issues on a typical page, but not all of it). Items that need human judgement are returned under "Needs manual review." It never claims a page is "compliant."

License

MIT