A11yScope

a11yscope-mcp

WCAG 2.2 AA checks for AI coding agents. The same engine as the A11yScope Chrome extension, exposed as an MCP server so Claude Code, Cursor, Claude Desktop and other MCP clients can audit the pages they build and fix what they find.

Runs locally in headless Chrome. Nothing is uploaded, no account, no telemetry.

Install

Claude Code

claude mcp add a11yscope -- npx -y a11yscope-mcp

Cursor / Claude Desktop / any MCP client — add to the MCP config:

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

Needs Node 20 or newer and a Chromium-based browser. Installing downloads nothing: the first scan uses the Chrome, Chromium, Edge or Brave already on the machine, and only if none is found does it fetch a Chrome for Testing build (~150 MB, once) into Puppeteer's cache. To point it at a specific browser, set A11YSCOPE_CHROME to the executable path.

Tools

Tool	What it does
scan_page	Loads a URL or a local HTML file in headless Chrome and returns violations grouped by rule, each with a CSS selector, an HTML snippet and a message that says what to change.
scan_html	Same, for an HTML string the agent just generated. Pass base_url if the markup references stylesheets on a reachable server; otherwise inline the CSS, since contrast checks need computed styles.
list_rules	The 31 checks, each with its WCAG 2.2 success criteria, level, impact and fix guidance.

Options on both scan tools: include_review (items that need a human decision), include_passed, max_findings_per_rule, viewport size. scan_page also takes wait_ms for pages that render late. If a site answers with a bot check (Cloudflare "Just a moment…" and the like), scan_page refuses with an error rather than scanning the interstitial, which would come back almost clean and mean nothing.

Typical prompt: "Scan http://localhost:3000 with a11yscope and fix every violation, then scan again."

Reading a result

Every rule comes back with a status (failed, review, passed or inapplicable) and a checked count: how many elements of the kind the rule targets were in the DOM (every <img> for img-alt, every link for link-name, 1 for page-level rules). A rule with nothing to test is inapplicable, not passed, and the summary splits rulesPassed from rulesNotApplicable. So "fix it, then scan again" has a tell: if img-alt went from 3 checked to 0 checked, the images were deleted, not described. excluded is how many of the checked elements the rule skipped as hidden (aria-hidden, display:none) or decorative (role="presentation"). A scan that goes from checked 3 / excluded 0 to checked 3 / excluded 3 means the images were hidden, not described; genuine decorative images exist, so treat that as a question for a human. Compare checked and excluded before and after, not just the violation count. Alt text that is a file name or a filler word (image, photo, icon…) is flagged by img-alt-redundant.

scan_html adds notes when the markup is a fragment (page-level checks then describe the fragment, not the page it will live in) or has no stylesheet (contrast and focus results reflect browser defaults).

Scope: the top document plus every same-origin frame inside it, at any depth. Findings from a frame carry the frame's path in their selector (iframe#chat >>> button), and page-level checks (language, title, h1, landmarks, skip link, heading order) apply to the top document only. Cross-origin frames are third-party content the author cannot change, so they are counted in summary.iframesNotEntered and named in a note, not scanned. Open shadow roots are entered the same way; closed shadow roots cannot be read by anything that runs in the page.

What it checks

Text alternatives (images, form labels, buttons, links, frames, SVG), colour contrast with the large-text and bold exemptions applied and translucent backgrounds composited, document structure (language, title, headings, main landmark, skip link, tables, lists, duplicate ids), and keyboard, pointer and ARIA (zoom lock, positive tabindex, aria-hidden focusable, nested interactive controls, 24×24 target size, autoplay, captions, invalid roles, required ARIA states, autocomplete, focus visibility).

Calibrated against sites built by accessibility practitioners: gov.uk, webaim.org, deque.com, a11yproject.com and w3.org/WAI all report zero violations. Anything reported there is treated as our bug until proven otherwise, and false-positive reports are the most useful thing you can send.

What it does not do

Automated checks find roughly a third of accessibility barriers. A clean result is a good sign, not a conformance claim. Whether alt text is accurate, whether a page makes sense in a screen reader, whether a keyboard user can finish a task — no tool can answer those, and this one does not pretend to. Anything it cannot decide comes back as review, not as pass or fail. It is not a substitute for an expert evaluation and does not certify compliance with the EAA, ADA, KWCAG or any other standard.

Licence

Copyright © 2026 Perceivable. Free to install and run, including commercially, through npm and MCP clients. The engine source is published so that "nothing leaves your machine" can be verified rather than trusted; it is not open source, and no licence is granted to copy, modify or redistribute it or to publish derivative works. Full terms: the LICENSE file in this package and at the repository root. Problems and false positives: https://github.com/perceivable/a11yscope/issues.