MCP Accessibility Scanner

MCP Accessibility Scanner 🔍

Accessibility checks inside your coding agent: axe scans, keyboard-focus checks and repeatable reports.

*An intentionally flawed local demo page, checked with automated tools. These annotations were generated by scan_page with annotateScreenshot: true, not added by hand.*

This MCP server lets your coding agent inspect a page, run axe checks, exercise keyboard focus and save findings for review. Automated checks don't certify WCAG compliance; manual accessibility testing is still needed. audit_screen_reader inspects the browser's accessibility tree, accessible names and element geometry. It does not test with an actual screen reader.

Quickstart: connect your coding agent

Install Google Chrome before the first audit. The configuration below uses system Chrome; installing the npm package does not install a browser. See browser configuration for alternatives.

Install the scanner:

npm install -g mcp-accessibility-scanner --allow-scripts=re2

The flag allows the native re2 dependency to install on npm 12. If a prebuilt binary is unavailable, its installer needs a native build toolchain; see re2's installation notes.

Add this stdio server to your coding agent's MCP configuration, then restart or reconnect the client:

{

"mcpServers": { "accessibility-scanner": { "command": "mcp-accessibility-scanner", "args": ["--headless", "--isolated", "--output-dir", "./a11y-output"] } } }

The client must be able to find the installed command on its PATH. --isolated uses a fresh browser profile, not your personal Chrome session. Output paths are relative to the server's working directory; use an absolute --output-dir if your client starts it elsewhere. Client-specific setup and other installation methods are in the reference below.

Your first audit

Start your app locally, then ask your connected coding agent to run these tools in order, replacing the URL with your app's address:

browser_navigate {"url":"http://localhost:3000"}

scan_page {"annotateScreenshot":true} audit_keyboard {"maxTabs":30} audit_screen_reader {}

These are MCP tool calls, not shell subcommands. For terminal use, see interactive mode.

scan_page returns text findings with JSON node details and remediation links. With annotateScreenshot: true, it also saves a full-page annotated PNG and returns a file resource link. It does not save a JSON report. audit_keyboard and audit_screen_reader save JSON reports and return summaries and report links; audit_site and scan_page_matrix also save JSON reports. There is no generated HTML report dashboard. Review incomplete checks, coverage warnings and the page states you haven't tested.

To reproduce the screenshot, serve the demo from this repository with python3 -m http.server 8765 --bind 127.0.0.1 --directory docs/assets, navigate to http://127.0.0.1:8765/accessibility-demo.html, then run scan_page with annotateScreenshot: true. The screenshot used a 1000×720 viewport (--viewport-size 1000,720).

Badges

Star History

Features

Accessibility Scanning

✅ Automated checks for WCAG 2.0/2.1/2.2 criteria (A, AA, AAA levels)\ 📄 Saved JSON audit reports and scan findings with remediation guidance\ 🎯 Support for specific violation categories (color contrast, ARIA, forms, keyboard navigation, etc.)

Browser Automation

🖱️ Click, hover, and drag elements using accessibility snapshots ⌨️ Type text and handle keyboard inputs 🔍 Capture page snapshots to discover all interactive elements 📸 Take screenshots and save PDFs 🎯 Support for both element-based and coordinate-based interactions

Advanced Features

📑 Tab management for multi-page workflows 🌐 Monitor console messages and network requests ⏱️ Wait for dynamic content to load 📁 Handle file uploads and browser dialogs 🔄 Navigate through browser history

Installation

You can install the package using any of these methods:

Using npm:

npm install -g mcp-accessibility-scanner --allow-scripts=re2

npm 12 does not run dependency install scripts unless you allow them. The scanner depends on re2, a native module whose install script downloads or builds re2.node; without it the server fails to start with Cannot find module './build/Release/re2.node'. Pass --allow-scripts=re2 to npm install -g and npx (older npm versions accept and ignore the flag). For a project dependency on npm 12 or later, run npm install-scripts approve re2 followed by npm rebuild re2 (approving does not run the script that was already skipped). On npm 11 and earlier, install scripts run by default; use npm rebuild re2 to restore a missing binary, provided scripts have not been explicitly disabled. To allow it for every global install on npm 12, run npm config set allow-scripts=re2 --location=user.

Installation with Docker

A pre-built image is available on Docker Hub. The image includes Chromium and is pre-configured for containerized use — no extra flags needed.

Pull from Docker Hub:

docker pull justasmonkev/mcp-accessibility-scanner

Claude Code

 claude mcp add mcp-accessibility-scanner -s user -- docker run -i --rm justasmonkev/mcp-accessibility-scanner

To persist screenshots and reports on your host, add a volume mount:

claude mcp add mcp-accessibility-scanner -s user \

-- docker run -i --rm -v /tmp/mcp-output:/app/output justasmonkev/mcp-accessibility-scanner

Without the -v mount, output files only exist inside the container and are lost when it exits.

Docker Compose

docker compose up -d

The Compose configuration publishes the unauthenticated MCP HTTP transport on 127.0.0.1:8931 only. Do not expose this port to untrusted networks.

Build from source

docker build -t mcp-accessibility-scanner .

Images built from this Dockerfile include tini as an init process; Docker's --init flag is optional.

Docker smoke test

npm run test:docker

Installation in VS Code

Install the Accessibility Scanner in VS Code using the VS Code CLI:

For VS Code:

code --add-mcp '{"name":"accessibility-scanner","command":"npx","args":["--allow-scripts=re2","mcp-accessibility-scanner"]}'

For VS Code Insiders:

code-insiders --add-mcp '{"name":"accessibility-scanner","command":"npx","args":["--allow-scripts=re2","mcp-accessibility-scanner"]}'

CLI Modes

The scanner can run in two modes depending on how you use it.

MCP server (default, no subcommand)

When launched without a subcommand, the process starts an MCP server that communicates over stdio. This is the mode used by MCP clients such as Claude Desktop, VS Code, and Claude Code -- you should never need to run it by hand.

npx --allow-scripts=re2 mcp-accessibility-scanner            # starts the MCP server (stdio)

All of the MCP client configuration examples in this README already use this default mode.

Interactive REPL (interactive subcommand)

For manual terminal use, the interactive subcommand starts a readline REPL where you can call any tool directly:

$ npx --allow-scripts=re2 mcp-accessibility-scanner interactive

Interactive mode. Type " " to call a tool. Ctrl+D to exit.

browser_navigate {"url": "https://example.com"}

scan_page {"violationsTag": ["wcag21aa"]}

audit_keyboard {"maxTabs": 30}

audit_screen_reader {}

Each line is . Omit the JSON to pass {}. Global browser connection flags still apply here, for example npx --allow-scripts=re2 mcp-accessibility-scanner --headless interactive. Use --mobile or PLAYWRIGHT_MCP_MOBILE=1 to emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit). It cannot be combined with --device, CDP attach/launch modes, remote browser endpoints, or --extension.

Browser extension mode

Use --extension to connect through the current Playwright Extension, which must support extension protocol v2.

npx --allow-scripts=re2 mcp-accessibility-scanner --extension

Controlled tabs are grouped by default. Pass --no-tab-group with --extension, set PLAYWRIGHT_MCP_NO_TAB_GROUP=1, or use "tabGroup": false in the config file to leave controlled tabs in their existing groups. This also applies when selecting the extension browser provider through --connect-tool; it has no effect on other browser providers. Connection approval and single-client tab ownership are unchanged. The environment accepts 1/true to disable grouping and 0/false to enable it, overriding the config file; --no-tab-group takes precedence over both.

This requires an extension build containing upstream change #43814 (commit deb7e86, October 31, 2026). As of November 1, the Chrome Web Store still lists version 0.4.0, updated September 1, which predates this change and ignores the setting. No supporting released version is confirmed yet; use a build containing that commit until one is available. The upstream manifest is also still 0.4.0, so the version number alone does not establish support.

Set PLAYWRIGHT_MCP_EXTENSION_TOKEN to the token shown by the extension to bypass the connection approval dialog. The relay's CDP WebSocket endpoint always requires a separate random token, generated per relay and appended automatically for the server's own connection. This CDP token is never passed in Chrome's launch arguments or extension URL; the extension approval token cannot authenticate a CDP client. Token-bypass connections are not background-safe: Chrome focuses the connection tab and window, and client-created tabs remain open after disconnect (upstream limitation). With a token, the extension must connect and finish setup within 30 seconds after the connection page opens. Failed attempts release the relay so the next tool call can retry. Without a token, manual approval waits until you approve or cancel the call. When --user-data-dir contains multiple Chrome profiles, the profile with the extension installed is selected automatically, preferring Chrome's last-used profile. Pass --profile-dir-name (or set PLAYWRIGHT_MCP_PROFILE_DIR_NAME) to select a profile explicitly; it requires --user-data-dir and accepts a Chrome profi