Audits web pages and HTML strings for WCAG 2.2 AA accessibility violations using a local headless Chrome instance.
Also known as perceivable/a11yscope, a11yscope-mcp
- Stars
- 1
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Oct 23, 2026
- License
- —
What is A11yScope MCP?
A11yScope audits web pages and HTML strings for WCAG 2.2 AA accessibility violations using a local headless Chrome instance. It exposes 3 tools, such as scan_page, scan_html, list_rules.
Summary generated from the project's README
About A11yScope MCP server
A11yScope provides automated accessibility auditing for developers using AI coding agents. It checks web pages and HTML strings against WCAG 2.2 AA standards by running a local headless Chrome instance. Because the engine runs on your machine, no data is uploaded to external servers and no accounts are required for operation. This makes it a private solution for inspecting the code generated by clients like Claude Code, Cursor, or Claude Desktop.
The server includes three specific tools: scan_page for URLs or local files, scan_html for code fragments, and list_rules to view the 31 available accessibility checks. It can inspect same-origin iframes and open shadow roots to ensure deep document coverage. Users can configure the viewport size, maximum findings per rule, and whether to include items requiring human review. The system uses existing local browsers like Chrome, Edge, or Brave, only downloading a specific build if no compatible browser is found.
What you can do with it
- 1Audit live web pagesRequest an AI agent to scan a specific URL for accessibility violations and fix them automatically.
Written from the project's README. Every use case is checked against a quote from it.
How to install A11yScope MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall A11yScope MCP in Claude Code
$ claude mcp add a11yscope -- npx -y a11yscope-mcpInstall A11yScope MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"a11yscope": {
"command": "npx",
"args": [
"-y",
"a11yscope-mcp"
]
}
}
}Install A11yScope MCP in VS Code
.vscode/mcp.json
{
"servers": {
"a11yscope": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"a11yscope-mcp"
]
}
}
}Install A11yScope MCP in VS Code CLI
$ code --add-mcp '{"name":"a11yscope","type":"stdio","command":"npx","args":["-y","a11yscope-mcp"]}'Install A11yScope MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"a11yscope": {
"command": "npx",
"args": [
"-y",
"a11yscope-mcp"
]
}
}
}Install A11yScope MCP in Codex
$ codex mcp add a11yscope -- npx -y a11yscope-mcpInstall A11yScope MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.a11yscope] command = "npx" args = ["-y", "a11yscope-mcp"]
Install A11yScope MCP in Gemini CLI
$ gemini mcp add -s user a11yscope npx -- -y a11yscope-mcpInstall A11yScope MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"a11yscope": {
"command": "npx",
"args": [
"-y",
"a11yscope-mcp"
]
}
}
}A11yScope MCP tools 3
Detected from the READMEscan_pagescan_htmllist_rules
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableperceivable/a11yscope is public and reachablegithub.com/perceivable/a11yscope ↗Pass
- Package names this repository as its sourcea11yscope-mcp names perceivable/a11yscope as sourcenpmjs.com/package/a11yscope-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-23github.com/perceivable/a11yscope ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from a11yscope-mcpPass
- No critical advisory in the package or its dependencies174 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHuba11yscope-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.
A11yScope MCP questions
How do I add A11yScope MCP to Claude Code?
Run claude mcp add a11yscope -- npx -y a11yscope-mcp in your terminal. Add --scope user to make it available in every project.
How do I add A11yScope MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does A11yScope MCP provide?
It exposes 3 tools, including scan_page, scan_html, list_rules.
Does my data get uploaded to a server?
No, the server runs locally in headless Chrome and nothing is uploaded, meaning no account or telemetry is required.
What happens if a site has a bot check like Cloudflare?
The scan_page tool will refuse to scan the interstitial page and return an error rather than scanning the bot check.
Can I use it to scan HTML code that hasn't been deployed yet?
Yes, the scan_html tool allows you to pass an HTML string directly to the agent for auditing.
Does this tool guarantee WCAG compliance?
No, automated checks only find about a third of accessibility barriers and a clean result is not a conformance claim.