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 "<tool-name> <json>" 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 <tool-name> <json-arguments>. 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

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 profile directory name such as Default or Profile 1 (see "Profile Path" at chrome://version). The PLAYWRIGHT_MCP_EXTENSION_TOKEN approval token is specific to the profile, so when selecting a profile explicitly, use the token shown in that profile.

Packed extensions require an enabled record in the profile's preferences; a leftover extension directory alone does not count as installed. Profiles whose preferences mark the extension disabled or uninstalled are excluded from automatic selection and rejected for explicit selection. Explicit selection with a custom executable skips local installation checks. A whitespace-only PLAYWRIGHT_MCP_PROFILE_DIR_NAME is treated as unset; other string environment variables retain their existing blank-value handling.

Discovering available tools (list-tools subcommand)

To print the built-in tool names and descriptions (page-registered WebMCP tools require a live MCP tools/list request):

npx --allow-scripts=re2 mcp-accessibility-scanner list-tools

Note: Tool names like browser_navigate and scan_page are MCP tool identifiers (and REPL commands in interactive mode). They are not shell subcommands -- you cannot run npx mcp-accessibility-scanner browser_navigate.

Configuration

Here's the Claude Desktop configuration:

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

Advanced Configuration

You can pass a configuration file to customize Playwright behavior:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["-y", "--allow-scripts=re2", "mcp-accessibility-scanner", "--config", "/path/to/config.json"]
    }
  }
}

Exact-name tool selection

npx --allow-scripts=re2 mcp-accessibility-scanner --allowed-tools browser_pdf_save --blocked-tools browser_evaluate,browser_file_upload

CLI	Environment	JSON config
--allowed-tools	PLAYWRIGHT_MCP_ALLOWED_TOOLS	allowedTools
--blocked-tools	PLAYWRIGHT_MCP_BLOCKED_TOOLS	blockedTools

CLI/environment values are comma-separated exact, case-sensitive names; JSON values are arrays of strings. allowedTools adds named tools to core and enabled capabilities; it is not a restrictive whitelist. For example, allowing browser_pdf_save does not disable navigation or accessibility audits, and allowing browser_install explicitly enables browser downloads without --caps install. Omitted lists preserve existing exposure defaults.

blockedTools wins over core tools, capabilities and allowedTools. Blocked tools are absent from tools/list and rejected on tools/call, even without prior listing and even when a request names a browser session. The server instructions sent at initialization stop recommending blocked tools, so clients are not directed to calls that would be rejected. If the blocked tool is the one that clears an open modal (browser_handle_dialog or browser_file_upload), the modal-state guidance names it and says it is blocked instead of offering it as the way forward; other tools keep refusing while the modal is open. The policy applies to standalone, CDP, extension, provider-switching and VS Code backends, over stdio and HTTP. browser_session_open, browser_session_close, accessibility tools and the proxy-owned browser_connect are not exempt. Allowing a tool does not bypass a provider's limitations or enable a connection mode; browser_connect still requires a mode that supplies it.

Precedence is CLI > environment > config file, independently for each list. A higher-precedence list replaces the lower one; lists are not merged. [] in JSON, --blocked-tools=, or an empty environment value explicitly clears that list (likewise for allowedTools). Empty lists add/block nothing; duplicates are harmless. Blank entries inside nonempty lists, non-array JSON values, unknown names (including generated webmcp_* page-tool names) and wildcards fail at startup.

Page-provided WebMCP tools remain discoverable by default and are outside this policy. Their generated webmcp_<name>_<identity> names hash an identity minted for each server run, document and registration, so a name copied from tools/list never matches after a restart or navigation. Instead of accepting a value that could never take effect, startup rejects webmcp_* names in both lists like any other unknown name. Page tools keep their existing scope and staleness checks; a persistent page-action policy would need a stable registration key and is not part of this feature.

This controls dispatch by tool name, not equivalent actions through other tools: for example, blocking browser_click does not prevent a page click through browser_evaluate. See the adoption decision.

Configuration Options

Create a config.json file with the following options:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": true,
      "channel": "chrome"
    },
    "cdpLaunch": {
      "command": "open",
      "args": ["-a", "Slack", "--args", "--remote-debugging-port={port}"],
      "startupTimeoutMs": 30000
    }
  },
  "timeouts": {
    "navigationTimeout": 60000,
    "defaultTimeout": 5000,
    "settle": 500,
    "idle": 0
  },
  "network": {
    "allowedOrigins": ["example.com", "trusted-site.com"],
    "blockedOrigins": ["ads.example.com"]
  },
  "snapshot": {
    "boxes": true
  }
}

Available Options:

• browser.browserName: Browser to use (chromium, firefox, webkit)

  With WebKit on the pinned Playwright 1.63.0, the contents of an open <details> nested inside a closed <details> count as visible: they appear in browser_snapshot and browser_find results, and browser_verify_element_visible and browser_verify_text_visible succeed for them. Chromium and Firefox hide them until the outer <details> is opened. The upstream fix is not in a stable release yet. The server does not filter snapshots or patch Playwright to work around this. See the verification notes.

• browser.allowedUploadDirs: Restrict files sent by browser_file_upload and browser_drop to regular files inside these directories, including resolved symlink targets. Restricted uploads and drops use a checked file handle and accept up to 50 MiB total per call. Unset allows any path; [] denies all file uploads and drops (text-only drops still work). Blank list entries are rejected. CLI: --allowed-upload-dirs (semicolon-separated; "" denies all), env: PLAYWRIGHT_MCP_ALLOWED_UPLOAD_DIRS (empty string denies all).

  The list must be an array, not null. Roots must exist at startup: their canonical paths are resolved once and retained for the server's lifetime, so retargeting a configured symlink does not grant access to a new tree. Non-empty upload allowlists require macOS or Linux with /proc/self/fd available. macOS blocks ancestor symlinks during the file open; Linux checks the opened descriptor's path. Other platforms reject restricted file uploads and drops rather than rely on race-prone pathname checks. Unrestricted uploads, deny-all lists, and text-only drops keep working on all platforms.

• browser.launchOptions.headless: Run browser in headless mode (default: true on Linux without display, false otherwise)

• browser.launchOptions.channel: Browser channel (chrome, chrome-beta, msedge, etc.)

• browser.contextOptions.clientCertificates: With client certificates, a configured launch proxy is also applied to fresh contexts unless browser.contextOptions.proxy explicitly overrides it. Playwright 1.63.0 ignores certificate-interceptor proxy bypass rules, so combining certificates with a nonblank effective proxy.bypass is rejected before launch. For a fresh context on a remote browser, configure its proxy explicitly; a proxy inherited only from that browser cannot be inspected. Existing attached contexts retain their current settings.

• browser.launchOptions.proxy: Browser proxy (CLI: --proxy-server, --proxy-bypass; env: PLAYWRIGHT_MCP_PROXY_SERVER, PLAYWRIGHT_MCP_PROXY_BYPASS). Credentials in a CLI or environment proxy URL, such as http://user:password@myproxy:3128, are moved into proxy.username and proxy.password so the browser can answer 407 Proxy Authentication Required; percent-encode reserved characters such as @, : or / in them. A proxy set in the config file keeps its explicit username and password fields.

  Authenticated proxy credential leak: The pinned Playwright 1.63.0 can send proxy credentials as website HTTP authentication after a proxy 407 challenge has been answered and cached, when a website responds with 401. This affects credentials supplied through --proxy-server, PLAYWRIGHT_MCP_PROXY_SERVER, browser.launchOptions.proxy, and browser.contextOptions.proxy. Avoid authenticated proxies until a release containing the upstream fix is adopted. Playwright 1.64.1, the latest stable release checked on October 20, 2026, also predates that fix. Startup emits one credential-free warning on stderr per configuration resolution when either configured proxy has credentials, including programmatic createConnection usage. The warning does not prevent the leak; unauthenticated proxies are unchanged. Proxies inherited only from an attached browser cannot be inspected or warned about by this server.