I turned my accessibility checker into an MCP server, so the agent that writes the HTML can also fix it

Last week I wrote about running my WCAG checker against gov.uk and finding that every one of the 72 "violations" was a bug in my checker. Fixing those left me with an engine I trust on real sites, packaged as a Chrome extension.

But the people who most need an accessibility check right now are not people. They are coding agents. Claude Code, Cursor and friends generate a huge share of new HTML, and they ship <img> without alt, grey-on-white placeholders and outline: none just like we did, only faster. An extension that a human clicks does nothing for that.

So the same engine is now an MCP server: a11yscope-mcp.

What it does

Three tools:

• scan_page loads a URL or a local HTML file in headless Chrome and returns violations grouped by rule. Every finding has a CSS selector, an HTML snippet and a message that says what to change.
• scan_html does the same for a string of markup, which is the one agents actually need: you just wrote this component, check it before you save it.
• list_rules returns the 31 checks with the WCAG 2.2 success criteria they map to.

The checks cover text alternatives (images, labels, buttons, links, frames, SVG), colour contrast with the large-text and bold exemptions applied and translucent backgrounds composited, document structure (language, title, heading order, main landmark, skip link, tables, lists), and keyboard, pointer and ARIA (zoom lock, positive tabindex, aria-hidden focusables, nested controls, the new 24×24 target size, autoplay, captions, invalid roles, required ARIA states, autocomplete, removed focus outlines).

Everything runs locally. It uses the Chrome, Chromium, Edge or Brave you already have, downloads nothing at install time, sends nothing anywhere.

Install

Claude Code:

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

Cursor, Claude Desktop or any other MCP client:

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

Then a prompt like "scan http://localhost:3000 with a11yscope and fix every violation, then scan again" closes the loop: the agent reads the selector and the message, edits the file, and re-scans until the list is empty.

What a result looks like

For a component with an unlabelled image and an empty link:

{
  "summary": { "violations": 2, "review": 1, "rulesRun": 31, "rulesFailed": 2, "rulesPassed": 28 },
  "rules": [
    {
      "id": "img-alt", "wcag": ["1.1.1"], "level": "A", "impact": "critical",
      "help": "Add alt text describing what the image conveys. If the image is purely decorative, use alt=\"\" ...",
      "violations": [{ "selector": "html > body > main > img", "message": "<img> has no alt attribute (src: a.png)", "snippet": "<img src=\"a.png\" width=\"120\" height=\"80\">" }]
    },
    {
      "id": "link-name", "wcag": ["2.4.4", "4.1.2"], "level": "A", "impact": "critical",
      "violations": [{ "selector": "html > body > main > a", "message": "Link has no discernible text", "snippet": "<a href=\"/x\">" }]
    }
  ],
  "disclaimer": "Automated checks find roughly a third of accessibility barriers. A clean result is a good sign, not a conformance claim; items marked review need a human decision."
}

That disclaimer is in every response on purpose. An agent will happily tell its user "the page is now WCAG compliant" if you let it. Roughly a third of barriers are machine-checkable; whether the alt text is true, whether the page makes sense in a screen reader, whether a keyboard user can finish the checkout, no tool can say. Anything the engine cannot decide comes back as review, not as pass.

Calibration

The gov.uk exercise became the acceptance test. gov.uk, webaim.org, deque.com, a11yproject.com and w3.org/WAI all return zero violations from this engine. Anything reported on those sites is treated as my bug until proven otherwise. If you hit a false positive, the issue tracker is the most useful place to put it: https://github.com/perceivable/a11yscope/issues

npm: https://www.npmjs.com/package/a11yscope-mcp

Comments

[Arhan Canli]

The closed loop ("fix every violation, then scan again") has a failure mode that the violation count can't see: the cheapest way to make img-alt or link-name go to zero is to delete the element, or to write alt="image". A re-scan reports a clean page either way. It would help to return something the agent can't satisfy by deletion, for example the element count per rule before and after (so "3 images checked, 0 now" reads differently from "3 images, all with alt"), and a review item for alt text that equals the filename or a stock word.

Same thing for rulesPassed: 28 in your sample: with two violations and one review out of 31, most of those passes are rules that found nothing to test, not rules that tested something and passed. For scan_html on a fragment it matters more, since contrast, heading order, landmark and skip-link rules depend on the page around the component. A separate notApplicable bucket (and a note when a fragment was scanned without the app's stylesheet) would stop the agent from reading "28 passed" as evidence about the whole page.

[Auten]

The "you just wrote this component, check it before you save it" framing for scan_html is the right one, and the disclaimer in every response is a good call.

One angle from the other side, from the Auten team: we build an MCP server that lets agents operate desktop apps through the accessibility tree. The same bugs your rules catch (unnamed buttons, empty links, nested controls) are exactly what makes an app hard for an agent to drive. An icon button with no name shows up as just "button", and the agent has to guess from pixels. So these fixes help screen reader users first, and agents that use the UI later too.

Question: how does scan_page handle components inside shadow DOM or same-origin iframes? That is where we most often see controls with no name in modern web apps.