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 "<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 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 explicitly overrides it. Playwright 1.63.0 ignores certificate-interceptor proxy bypass rules, so combining certificates with a nonblank effective 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.

CLI equivalents are also available: --cdp-launch-command, --cdp-launch-args, --cdp-launch-cwd, --cdp-launch-port, --cdp-launch-startup-timeout, --cdp-endpoint, --cdp-header (repeat for multiple headers, e.g. --cdp-header "Authorization: Bearer <token>"), and --cdp-timeout. The CDP headers and timeout can also be set via the PLAYWRIGHT_MCP_CDP_HEADERS (one Name: Value entry per line) and PLAYWRIGHT_MCP_CDP_TIMEOUT environment variables.

If CDP attachment times out after the WebSocket connects, an existing tab may be blocking Playwright's browser initialization. On the pinned Playwright 1.63.0, a tab without a renderer — one whose renderer crashed, or one discarded by Chrome's Memory Saver — is never answered, so the attach cannot succeed while that tab exists (upstream fix, unreleased); a sleeping or unresponsive tab can stall it too (upstream report). --cdp-endpoint then fails after --cdp-timeout, and --cdp-launch by --cdp-launch-startup-timeout (each attach attempt also stops at --cdp-timeout), with an error that names this cause; --cdp-launch stops only the application it launched. For --cdp-endpoint, use an explicit positive --cdp-timeout to bound the attempt; 0 disables it and the attach can then wait forever. Reload or close the affected tab yourself, or attach to a separate disposable browser. noDefaults and --isolated do not skip initialization of existing tabs; the server does not close or reload your tabs or bypass Playwright's initialization to work around this. See the verification notes.

Playwright 1.63 does not support back/forward-cache (BFCache) restoration: an attached browser with BFCache enabled can return unusable references and omit iframe contents after back navigation. This was reproduced with full Chromium, Chrome, and Edge. For a browser you launch yourself, include --disable-back-forward-cache before attaching, or use the server's normal browser launch mode, which retains Playwright's default flag. The server does not change an attached browser's flags or replace back navigation with a reload. See the upstream maintainer's explanation, Playwright's BFCache limitation, and the verification and reproduction command.

HTTP listeners accept Host headers for loopback aliases, the bound non-wildcard address, and the configured hostname (--host, server.host, or PLAYWRIGHT_MCP_HOST). A named host must resolve to an address on the server to bind; other hostnames remain forbidden. Wildcard binds (--host 0.0.0.0 or --host ::) do not allow arbitrary hostnames or the wildcard address itself: use a loopback hostname or bind a specific hostname/address. Missing or invalid Host returns 400; disallowed hosts return 403. When present, Origin must use HTTP and exactly match the normalized Host hostname and port; HTTPS or a different authority returns 403. These checks also apply with bearer authentication, which still requires a loopback listener.

For remote HTTP access, configure the TLS reverse proxy explicitly. For example, with the MCP server bound using --host 127.0.0.1 --port 8931 and PLAYWRIGHT_MCP_AUTH_TOKEN set:

• Accept only your configured public hostname over HTTPS and forward /mcp to http://127.0.0.1:8931/mcp.
• Set the upstream Host header to 127.0.0.1:8931, not the public hostname. Forward the client's Authorization header unchanged; do not inject a shared token for unauthenticated clients.
• Before removing Origin, reject any non-empty value outside your explicit trusted HTTPS origin list (for example, https://mcp.example.com). Allow absent Origin for non-browser clients. Then remove Origin upstream, or rewrite it to http://127.0.0.1:8931. Never strip arbitrary origins without checking them first.
• Disable response buffering for SSE streams. Browser clients on a different origin also need a narrowly scoped CORS policy at the proxy.

The server does not trust Forwarded or X-Forwarded-* to bypass its checks. Preserving the public Host or HTTPS Origin upstream returns 403, even with a valid bearer token.

Unexpected HTTP request setup failures, including stateful initialization, return a generic error with HTTP status 500. Parsed legacy JSON-RPC requests retain their IDs, batch errors omit notifications, and notification-only failures have an empty response body. Failed or rejected initialization disposes its unregistered backend. If the request body is still unread or the response has already started, the connection is closed instead of remaining available for reuse.

Caller-supplied screenshot, PDF, find-result, scan-page-matrix, and audit report filenames use a no-clobber policy: an existing file causes the tool call to fail instead of being overwritten. Windows-reserved basenames and names ending in a dot or space are rejected on every platform so configured names behave consistently across hosts.

Failed download saves are reported as tool errors in the current or next response, including after the tab closes; failed entries do not advertise a saved file or an ongoing download. The server retains up to 20 bounded error messages between responses and reports any omitted count. Full Chromium-family browsers on Playwright 1.63.0 have verified native crashes after persistent-profile relaunch. Error reporting does not fix that native crash. The explicit --isolated control passed, but does not preserve a profile between launches; use recorded storage state when needed for authentication. Existing profiles and browser defaults are preserved.

Use --timeout-settle or PLAYWRIGHT_MCP_TIMEOUT_SETTLE to override the post-action settle delay. It applies after every action so delayed DOM-only updates are included in the response; a short observation window also catches scheduled requests and waits for them before that delay.

Use --timeout-idle 300000, timeouts.idle, or PLAYWRIGHT_MCP_TIMEOUT_IDLE to release the default browser after five idle minutes. Shared contexts stay open while any client is working; the idle window starts after the last tool call or download finishes. Explicit recordings prevent idle release until browser_stop_recording finishes; passive --save-session capture does not. Cleanup finalizes traces. The next browser tool call reopens the connection and includes a note to navigate again and refresh element references. Attached CDP, extension, and VS Code browsers are disconnected; their external pages remain open. Close and session-management tools do not relaunch an idle browser. Explicit browser_session_open handles keep their separate PLAYWRIGHT_MCP_BROWSER_SESSION_TTL_MS behavior. Zero disables this feature; blank environment values leave the existing configuration unchanged.

The VS Code browser_connect tool accepts only playwright or playwright-core libraries and loopback WebSocket URLs. Set PLAYWRIGHT_MCP_VSCODE_ALLOW_REMOTE=1 to allow remote endpoints, which must use wss:. URL userinfo credentials are rejected.

HTTP Heartbeat

When the server runs with --port, it sends MCP heartbeat pings after a Streamable HTTP client opens the optional event stream. POST-only clients stay connected without heartbeat because server-initiated requests cannot reach them. Set PLAYWRIGHT_MCP_PING_TIMEOUT_MS to override the default 5000 ms timeout, or to 0 or any negative value to disable heartbeat pings. A client that answers ping with a JSON-RPC "method not found" error is treated as alive: the server stops heartbeating that session instead of closing it. Only an unanswered ping (timeout) or a transport failure closes the session.

Clients without the initialize handshake

Clients on the MCP 2026-07-28 revision no longer send the initialize handshake. With --port, requests carrying the revision's per-request _meta envelope are served natively on the 2026-07-28 protocol: server/discover is answered (so clients negotiating with versionNegotiation: 'auto' or a 2026-07-28 pin connect directly), results carry resultType and the SEP-2549 cache fields — dynamic browser tool lists use the conservative ttlMs: 0 default instead of a one-hour cache — and the SEP-2243 standard headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name) are validated against the request body. Older handshake-free clients (2025-era requests without the envelope) are served statelessly as before. In both cases requests receive no heartbeat pings, and in the modes where the server creates browser contexts itself each request runs against a fresh default browser session: with the default persistent profile the per-request default context runs in its own disposable profile (like an explicit browser session), so parallel handshake-free requests do not contend for the stable profile — and the stable profile's sign-in state is not visible to them — while --isolated, remote endpoints and isolated CDP modes mint a fresh context per request anyway. Modes that reuse one live browser context are the exception: --extension (and a browser_connect or VS Code session switched to a connected-browser provider) and CDP attach without --isolated serve every handshake-free request from the same shared context, so its tabs, cookies and storage persist across requests — the same sharing that makes these modes refuse browser_session_open (in --vscode serving the session tools are the exception: they are host-scoped and keep running against the default provider even while switched — see Browser Session Tools). With a pinned --cdp-launch-port, only one launched application can be served at a time, so a second handshake-free request arriving while another request's browser context is still live is rejected with a clear error instead of silently attaching to the first request's application. With --user-data-dir, each handshake-free request launches a browser in the one configured profile: the profile's state persists across requests, and parallel requests contend for its browser lock and can fail with "Browser is already in use". Elsewhere, browser state that must persist across handshake-free requests belongs in an explicit browser session — a browserSessionId handle minted by browser_session_open in one request resolves in later ones (see Browser Session Tools). Clients that do send keep the classic session behavior unchanged. When several such stateful clients are connected at once in the default persistent-profile mode, the first client's default context holds the stable profile — concurrent clients' default contexts run in their own disposable profiles (without the stable profile's sign-in state) until it is freed, instead of failing with "Browser is already in use".

Auditing pages behind a login

Most real audits target pages that only exist for a signed-in user. There are two ways to get there.

Interactive route (no setup)

Keep every step in the same browser session. Within that session, audit_site crawls in a temporary tab of the same browser context, so cookies and local storage created while you drive the browser are available to the crawl:

1. browser_navigate to the login page
2. browser_fill_form / browser_click to sign in
3. browser_navigate to the first page you want audited
4. audit_site — the crawl inherits the session you just created

The interactive CLI, stdio MCP and initialized stateful HTTP connections can use their default session for this sequence. Handshake-free HTTP clients must call browser_session_open first and pass the returned browserSessionId to every navigation, interaction and scan call when using a mode that creates contexts per request. Otherwise the next request starts a new default context and loses the login and page state. Shared-context modes such as --extension and non-isolated CDP attach reject browser_session_open; use their shared context or a stateful connection instead. See Browser Session Tools for mode-specific behavior.

With the default persistent profile, sign-in state also survives across server restarts, so you usually only sign in once. The default profile is keyed to the server's working directory, so each workspace's server keeps its own sign-in state — servers launched for different workspaces neither share cookies nor contend for the same profile.

When a login form does not advance

• Take a fresh browser_snapshot after a rerender and use its current field references. Wait for an application-specific ready message with browser_wait_for before entering data.
• browser_fill_form and ordinary browser_type use Playwright's fill. If the application requires individual key events, clear the field with browser_type and text: "", then use browser_type with slowly: true. Slow typing appends characters; it does not clear an existing value.
• Verify an authenticated page or account-specific element before scanning. A filled field or successful click is not proof of a successful login. Inspect browser_console_messages and browser_network_requests if submission fails; avoid sharing passwords, tokens or private response bodies in bug reports.
• In Docker, the browser runs inside the container: localhost names the container, not your host's development server. Use a host address reachable from that container and configure the development server to accept that specific address. Check its bind address, allowed hosts and authentication origin/redirect settings; do not disable host checks or widen CORS as a blanket fix.

Direct DOM value assignments can bypass application event handlers, and synthetic setters are not a general fix for controlled inputs. Report the scanner version, browser mode, exact tool arguments (with secrets removed) and a minimal local reproduction if the standard interactions still fail.

Storage state route (repeatable, CI-friendly)

Record a session once with Playwright's codegen, then hand the file to the server:

npx [email protected] codegen --save-storage=auth.json https://example.com/login

Sign in in the opened browser, then close it — auth.json now holds the cookies and local storage.

Pass it to the server with the CLI flag, the environment variable, or the config file:

npx --allow-scripts=re2 mcp-accessibility-scanner --isolated --storage-state ./auth.json

PLAYWRIGHT_MCP_ISOLATED=true PLAYWRIGHT_MCP_STORAGE_STATE=./auth.json npx --allow-scripts=re2 mcp-accessibility-scanner

{
  "browser": {
    "isolated": true,
    "contextOptions": {
      "storageState": "./auth.json"
    }
  }
}

Every supported mode handles the state — by applying it or refusing it.

Playwright 1.63.0 safety restriction: importing into an existing context is rejected before taking a rollback snapshot or resetting any storage. On this pin, snapshot capture can execute service-worker-served scripts for a previously visited origin whose tab is no longer open (upstream fix). Use a fresh context, or omit --storage-state and sign in interactively. Service workers are not disabled. A future dependency upgrade must also pass the recorder/shared-client checks in #218 and IndexedDB checks in #224 before this restriction is reconsidered.

IndexedDB snapshot limitation: on pinned Playwright 1.63.0 with Chromium 153.0.8010.12 and Firefox 155.0, storageState({ indexedDB: true }) loses Map and Set contents. Both newContext({ storageState }) and setStorageState() restore them as empty plain objects; ordinary JSON records survive. Fresh contexts protect existing browser data, but cannot recover values already lost during capture. The upstream fix is merged but is not in this pin. Before allowing imports into existing contexts again, verify both restore paths preserve Map/Set types and entries on each supported engine, including after a failed import. The real-browser regression in tests/browser-failures.integration.test.ts checks that rejecting an import leaves the original Map/Set records intact and that isolated JSON IndexedDB imports still work.

• Fresh-context modes (--isolated, the remote-endpoint mode, or either CDP mode combined with --isolated): the context is created with the storage state directly.
• Default persistent-profile mode with --storage-state: the session runs in a fresh, disposable profile — unique to that session and removed when it closes — built from the state, so the recorded state is provably the only session data (without --storage-state the regular persistent profile is used and survives restarts, as before). Any page the launch opened (for example from a URL in browser.launchOptions.args) is parked on a blank replacement before the state lands, then the replacement is navigated to the same URL, so a still-running anonymous page cannot overwrite the recorded identity and a scan never reads its DOM. This also means cannot be combined with (a user-supplied profile carries its own session and will not be wiped; the server refuses the combination).

Keep the crawl from destroying its own session

audit_site excludes logout|signout by default, which is not enough for most applications. Add anything else that ends or changes the session before you start the crawl:

{
  "excludePathPatterns": ["logout|signout", "account/(close|delete)", "sessions/revoke", "/switch-(locale|account|org)"]
}

Note that excludePathPatterns replaces the default rather than extending it, so repeat logout|signout in your list.

If a session cookie disappears anyway, audit_site says so instead of reporting a confident, wrong audit: the result starts with a WARNING: cookie(s) … disappeared while loading <url> line, and both the JSON report and the structured content carry a sessionLosses list naming, for each lost cookie, the page that dropped it — the page reached after any redirect, and reported even when that page failed to finish loading. If one of the lost cookies was the session, every page scanned after that point was audited as a signed-out user — exclude the offending URL, sign in again, and re-run.

The check compares which cookies the crawled URLs carry, not their values, so a rotating CSRF token never reads as a lost session. A cookie the browser deleted at its own stated expiry is ignored for the same reason — Cloudflare's __cf_bm lives 30 minutes and would otherwise warn on any longer crawl. Beyond that no attempt is made to tell an authentication cookie from any other: nothing in a cookie marks it as one, so any cookie the crawl started with and later lost is reported. Monitoring does not stop at the first loss — each cookie is reported once, at the URL where it vanished, so an analytics cookie expiring early cannot mask the session cookie being dropped later. URLs discovered mid-crawl join the cookie tracking before they are visited, so a session cookie scoped to a path below the start URL (say /app) is watched too.

Available Tools

Page-registered WebMCP tools

When the current page exposes a supported WebMCP API, MCP tools/list includes its tools as webmcp_<name>_<identity> alongside built-in tools. In --extension mode without PLAYWRIGHT_MCP_EXTENSION_TOKEN, listing never starts the extension connection, since that waits for your approval: page tools are listed once a browser tool call has connected it, and stateless (handshake-free) requests need the token to list them at all. Use the exact returned name: names are scoped to the browser session, frame/document and registration, and stale names are rejected rather than redirected to another action. Because of that, --allowed-tools / --blocked-tools cannot select them. No browser flags or polyfills are installed automatically.

To discover or invoke tools in an explicit browser session, put its handle in request metadata (params._meta.browserSessionId) on both tools/list and tools/call. This is separate from params.arguments: page-defined browserSessionId and _meta arguments are preserved unchanged. Without routing metadata, discovery and invocation use the default session. Session handles are never enumerated by discovery. Listing holds its session against closure or expiry until discovery completes or the request is cancelled.

Names, descriptions, schemas, results and page errors are untrusted. Every page tool retains conservative action annotations even if the page claims it is read-only. Calls are bounded and cancellable, but a timed-out or cancelled page action may still be running; do not retry it blindly. Stateful connections receive deduplicated list-change notifications for their last listed scope; stateless clients should re-list rather than cache the result.

Native Chromium WebMCP invocation supports the JSON-string contract in Chromium 153 and the object-input contract verified in Chromium 156, including external CDP connections. The bridge selects the contract from the native method's signature before invocation; page-provided JavaScript shims keep JSON-string inputs. An invocation error never triggers an automatic retry.

Stateful proxies buffer catalog changes until pending tool listings return, including changes arriving just as a listing finishes, so refresh notifications follow the returned catalog.

See WebMCP usage, limits and tests for request examples, discovery limits and validation commands. Page descriptors must pass the MCP SDK’s tool-schema validation, and their input schemas must compile with the validator that later checks call arguments, before publication. Schemas that define pattern or patternProperties subschemas, or declare a root type other than object, are omitted; format keywords are advertised but left for the page to enforce, and argument validation is interrupted after 500 ms. An empty listing is not proof that the page has no tools: unsupported, invalid or timed-out registrations are omitted.

Built-in tools

The MCP server provides comprehensive browser automation and accessibility scanning tools:

Core Accessibility Tool

scan_page

Performs a comprehensive accessibility scan on the current page using Axe-core.

Parameters:

• violationsTag: Array of WCAG/violation tags to check
• includeIncomplete (default true): also report Axe "incomplete" results
• maxNodesPerViolation (default 10): cap on node details reported per rule; occurrence totals use all deduplicated findings, not the capped sample
• includeSelectors / excludeSelectors: CSS selectors that scope the scan
• withRules / disableRules: Axe rule ids that narrow which rules run
• annotateScreenshot (default false): capture an annotated screenshot of the violations

Annotated screenshots: When annotateScreenshot is true, each violating element is outlined and labelled with the rule ids it failed, a full-page PNG is written to the MCP output directory (scan-page-annotated-{timestamp}-{token}.png) and returned as a resource link, and the markers are then removed so the page is left exactly as it was. The markers are drawn in an out-of-flow overlay clipped to each element's own box, so they never reflow the page. The overlay uses a fresh id per scan, is placed in the browser's top layer so it stays visible over an open dialog, popover or fullscreen element, and compensates for a CSS zoom or a scaled ancestor so markers line up with what is rendered. An element that fails several rules gets one box listing every rule id, and elements inside open shadow roots are marked by walking the shadow path Axe reports. Running animations are frozen at their current time before the elements are measured and resumed after the capture, so a moving target keeps its marker. The markers themselves live in a shadow root under an overlay whose own styles are !important, so page CSS cannot restyle or hide what the report counts, and each rule label sits outside the clipped box so it stays readable on an element smaller than its own label. At most 50 elements are annotated per scan. The result text always reports how many nodes were marked out of the total, plus how many were left out because they exceeded the limit, were hidden, zero-size or off-canvas (a full-page screenshot is clipped to the document box), or were inside an iframe (cross-frame selectors cannot be resolved from the top document).

Supported Violation Tags:

• WCAG standards (in the default set): wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, wcag22aaa
• Section 508 (in the default set): section508
• Categories (opt-in): cat.aria, cat.color, cat.forms, cat.keyboard, cat.language, cat.name-role-value, cat.parsing, cat.semantics, cat.sensory-and-visual-cues, cat.structure, cat.tables, cat.text-alternatives, cat.time-and-media
• Non-conformance tags (opt-in): best-practice, experimental (see the caveat below -- a few experimental rules also carry a WCAG tag and run by default)

The default set is the WCAG and Section 508 tags only, so a default report means "this fails a conformance criterion". Category tags are opt-in for that reason: Axe matches requested tags with OR, so asking for cat.keyboard also pulls in best-practice rules such as region and skip-link that carry both tags. No live conformance rule is lost by leaving them out: the only rules reachable only through a cat.* tag are duplicate-id and duplicate-id-active, which Axe marks deprecated because WCAG removed SC 4.1.1. Add best-practice (landmark structure, heading order, tabindex hygiene) or a cat.* tag when you want that broader review.

The same OR semantics apply to experimental, with one deliberate exception: four experimental rules -- css-orientation-lock (SC 1.3.4), p-as-heading, table-fake-caption and td-has-header (SC 1.3.1) -- also carry a wcag* tag and so run in the default set. In Axe, experimental describes how settled the heuristic is, not whether the criterion is real, so these are kept rather than filtered out. Adding the experimental tag pulls in the remaining experimental rules, which have no conformance tag of their own. Axe 4.14 no longer marks label-content-name-mismatch (SC 2.5.3) as experimental; it still runs by default.

Scan scoping: scan_page, audit_site, and scan_page_matrix accept includeSelectors and excludeSelectors to limit what Axe looks at. Use includeSelectors to audit one component (["#checkout-form"]) and excludeSelectors to drop third-party noise that pollutes every report (["#cookie-banner", "iframe.intercom-frame"]). Exclusions are applied after inclusions, so you can carve a widget out of an included subtree.

Selectors are resolved before the scan runs:

• Syntactically invalid CSS fails the scan, naming the selector.
• An includeSelectors entry that matches nothing fails the scan. Axe on its own would accept a partly-matching include set and quietly scan less than you asked for, so the scanner refuses rather than returning a clean-looking report with half the scope missing.
• An excludeSelectors entry that matches nothing is a no-op, not an error -- a crawl legitimately visits pages that lack the excluded widget.

In audit_site, selectors apply to every crawled page, so an includeSelectors value that is absent from a given page marks that page as errored in the report while the crawl continues. Link discovery runs before the scan, so pages reachable only through an errored page are still crawled.

Rule-level control: scan_page, audit_site, and scan_page_matrix accept withRules and disableRules to pick individual Axe rules instead of whole tag sets. Use withRules to re-check one rule after a fix (["color-contrast"]) and disableRules to mute a rule you have already triaged (["region"]). Rule ids are the ones Axe reports (image-alt, color-contrast, ...); see the Deque rule reference.

• withRules overrides violationsTag. Axe can run either a rule list or a tag list, never both, so when withRules is set the tags are ignored entirely -- withRules: ["image-alt"] runs exactly that one rule regardless of violationsTag. Rule ids are the more specific request, so they win.
• disableRules subtracts from whatever is selected. It applies to violationsTag and withRules alike. (Axe itself ignores disabled rules once you give it an explicit rule list; the scanner subtracts them up front so the two options mean the same thing together as apart.) Disabling every rule in withRules is an error rather than an empty scan.
• An explicitly empty withRules is an error too. withRules: [] selects no rules, and silently falling back to the tag set would run a different scan than the one requested — omit the option to scan by tags instead. Clients that build the list dynamically should drop the key when the list comes out empty.
• Unknown rule ids fail the scan, naming the id. Both options are checked against Axe's rule catalogue before the browser is touched, so a typo is reported as Unknown Axe rule id(s) in withRules: image-altt rather than surfacing later as an frame.evaluate failure from inside the page. Rule ids apply to a whole run, so audit_site and scan_page_matrix check them once before they touch the page -- a bad id fails the call outright instead of crawling every URL, or reloading and re-emulating the page, before rejecting the argument.

audit_site and scan_page_matrix record both values in their JSON report metadata, so a stored report can be told apart from a full scan.

Incomplete ("needs review") results: Axe returns incomplete for checks it cannot decide on its own -- contrast over a background image or gradient, ambiguous labels, elements it could not fully evaluate. scan_page, audit_site, and scan_page_matrix report these in a section separate from violations so you can resolve them by inspecting the page (screenshot, snapshot, browser_evaluate). Set includeIncomplete: false to suppress their detailed findings. In matrix scans, this does not disable the comparison-validity checks described below.

Frames that could not be scanned: Axe is installed into every frame of the page before the scan runs. A frame that navigates mid-injection, or whose renderer does not answer within a second, is left out -- and its contents then contribute no findings. Rather than let that pass as a clean result, all three scan tools print a WARNING: Axe could not be installed in N frame(s) block listing the frame URLs, and audit_site and scan_page_matrix also record them per page and per variant in their JSON reports (unscannedFrames) and in structuredContent. A frame that was still loading usually succeeds on a re-run; one that fails consistently has to be audited on its own.

A nested frame is reported when any frame above it went unscanned, even if its own injection succeeded: Axe reaches a nested document only by relaying through the frames above it, so an outer frame without Axe takes everything below it out of the scan.

A frame you scoped out yourself is not reported: with excludeSelectors: ["iframe.intercom-frame"] that widget failing to load is the outcome you asked for, not a gap. Scope is resolved through the whole frame chain and across shadow boundaries, so an includeSelectors entry naming an ancestor still covers frames nested several levels below it or inside a shadow root, and excluding an outer frame or a shadow host silences everything inside it. Anything the check cannot resolve is reported rather than hidden.

Audit Tools

audit_site

Crawls and scans multiple internal pages, then aggregates violations across the site.

• Default strategy: link-based BFS from the current URL
• Supports links, nav, sitemap, and provided URL strategies
• Sitemap URLs and every redirect must pass the server network policy and crawl scope. Fetches run on the MCP host, use HTTP(S) without browser cookies or auth headers, and have a 15-second total timeout, 20-redirect cap, and 10 MiB response limit. Browser proxy settings, browser.remoteEndpoint, browser.cdpEndpoint (including loopback endpoints, which may tunnel to remote browsers), and switched browser_connect providers are rejected for this strategy; use provided URLs in these modes. Sitemap TLS certificates must be valid even when browser HTTPS errors are ignored.
• Always writes a JSON report (default filename: audit-site-{timestamp}-{token}.json). Per-page summary.totalNodes, byImpact, and byRuleId count all deduplicated violation nodes; maxNodesPerViolation only limits the saved node details.
• After browser navigation settles, the reached URL is checked again against HTTP(S), sameOriginOnly, includeSubdomains, and excludePathPatterns. A destination outside that scope is recorded as a page error naming the requested and reached URLs; it is not scanned or used for link discovery, and the crawl continues. This is a post-navigation check, not a network-request blocker: redirect destinations may already have been contacted and changed session state.
• A page that opens an alert, confirm or prompt while it is being audited is reported as an errored page as soon as the dialog opens, with the dialog named in its error. This includes terminal HTTP 3xx pages (for example, 300 or 302 without a Location) that commit a document instead of redirecting. The crawl never answers a dialog: it closes that page's tab and continues with the next URL in a fresh one, so one such page does not fail or hang the pages after it. A dialog the previous page raises while the crawl is already navigating away is not blamed on the next page, which is audited again in the fresh tab. Same-document history updates, even ones that keep the exact URL unchanged, do not count as the next page loading. A fresh tab starts without the old tab's sessionStorage, so the result then starts with a WARNING: … continued in a fresh tab from <url> line and both the JSON report and the structured content carry a crawlTabRestarts list; if the site keeps its session in sessionStorage, pages from that URL on may have been audited in a different session. The tab the tool was called from is not touched.

Example flow:

1. Navigate to your site homepage with browser_navigate
2. Run audit_site with maxPages: 25 and maxDepth: 2
3. Review the report path returned by the tool (written to the MCP output directory)

scan_page_matrix

Runs Axe scans on the same page across viewport/media/zoom variants and compares deltas against baseline.

• Default variants: baseline, mobile, desktop, forced-colors, reduced-motion, zoom-200
• Supports custom variants and optional reload between variants
• Always writes a JSON report (default filename: scan-matrix-{timestamp}-{token}.json)
• JSON report and structured result schema v2 set baseline deltas to null when either scan left frames unscanned, or when a rule recorded as a violation on either side also has incomplete results on either side. An undecidable result is not evidence that a violation was fixed, introduced, or changed in count.
• Each variant includes comparisonIncompleteRuleIds in JSON and structured output: the sorted rule IDs making its comparison uncertain, or [] when none do. The text table distinguishes missing-frame coverage from incomplete checks. These safeguards still apply with includeIncomplete: false; that option hides detailed findings, not comparison validity.
• Unrelated incomplete-only rules do not suppress comparisons of confirmed violations. The baseline self-comparison is also unavailable if the same rule has both violating and incomplete nodes.
• Summary totals and baseline count deltas use all deduplicated violation nodes, while saved node details remain capped by maxNodesPerViolation. Changing that cap does not change occurrence totals.

Example flow:

1. Navigate to a page state you want to validate
2. Run scan_page_matrix with defaults (or provide custom variants)
3. Review per-variant deltas and open the generated JSON report path

audit_keyboard

Audits real keyboard focus behavior by pressing Tab (and optional Shift+Tab) with practical heuristics.

• Checks skip links, focus visibility, focus jumps, and possible focus traps
• Restores the original URL after cross-document skip-link navigation. It uses Back for a single observed history-entry increase, verifies the restored URL, and otherwise replaces the current entry with the original URL. Fragment jumps, same-document history changes, and same-URL reloads do not consume an earlier history entry. When forward history was truncated or an entry was replaced, restoration can reload the audited page rather than recover its previous document state.
• Checks target size against WCAG 2.2 SC 2.5.8 (checkTargetSize, default on)
• Checks that focus is not entirely obscured, WCAG 2.2 SC 2.4.11 (checkFocusObscured, default on)
• Optional issue screenshots (screenshotOnIssue)
• Always writes a JSON report (default filename: audit-keyboard-{timestamp}-{token}.json)

Limits of the WCAG 2.2 checks — these are heuristics, not a conformance verdict:

• Target size only inspects elements the tab order actually reaches, so pointer-only targets are never measured.
• Of the SC 2.5.8 exceptions, only spacing (a 24px-diameter circle centered on the target must reach neither another target's box nor another undersized target's circle) and inline (an inline-level target — inline, inline-block, inline-flex, … — inside surrounding sentence text, found by walking out through inline wrappers such as <strong> to the containing block) are evaluated. The user agent control, essential, and equivalent exceptions cannot be detected from the DOM, so a target relying on one of them is still reported and needs manual triage.
• Spacing neighbours use the same pointer-target rule as the focused element, so rendered :disabled controls are not counted as neighbours, and contenteditable regions are counted as targets on both sides.
• Target size uses the element's bounding box, so an inline target wrapped over several lines is measured as one union box rather than per line, and a target whose visible area is cut down by an overflow or clip-path ancestor is measured at its full unclipped size.
• SC 2.4.11 is the Minimum (AA) level: a focused element is only reported when every sampled point of its box is covered by other content. Partially covered focus passes here, and the stricter SC 2.4.12 (AAA) is not checked. It applies to every focus stop with a rendered box, including elements that are not pointer targets such as iframes.
• Coverage is measured by hit-testing sample points and then checking that the element hit actually paints (visible, non-zero opacity all the way up to the first wrapper shared with the focused element, non-transparent background or background image). A transparent click-catching overlay therefore does not count as obscuration, but a covering layer with pointer-events: none is never returned by hit testing and is missed. Semi-transparent overlays that still leave content legible are reported.

Example flow:

1. Navigate to the target page and let it fully load
2. Run audit_keyboard with maxTabs: 50
3. Review focus findings and open the generated JSON report path

audit_screen_reader

Inspects the browser's accessibility tree (page.ariaSnapshot), accessible names and element geometry for potential accessibility issues. No actual screen reader is installed or driven, and its announcements and interactions are not tested.

Checks (checkNames)

• missing-accessible-name: controls and images exposed with no accessible name (WCAG 4.1.2)
• uninformative-accessible-name: names such as "click here", "read more", "image" that mean nothing out of context (WCAG 2.4.4)
• filename-as-accessible-name: image alt text that is a file name, e.g. IMG_1234.jpg, DSC00123 (WCAG 1.1.1). Only images are checked: a link or button legitimately named after the file it downloads (logo.png) is not a defect.
• label-in-name-mismatch: the accessible name does not contain the visible label, which breaks voice control (WCAG 2.5.3). The visible label of <input type="submit|button|reset"> is read from its value, and a web component's label is read from its open shadow root.
• duplicate-accessible-name: sibling links with the same name that lead to different URLs (WCAG 2.4.4)

Name comparisons normalize canonically equivalent Unicode text, so composed and decomposed spellings such as Café are treated consistently.

Check (checkReadingOrder)

• reading-order-mismatch: accessibility tree order (what is read) versus visual position (WCAG 1.3.2), i.e. order, flex-direction: row-reverse, absolute positioning

What it deliberately does not detect

• Reading order is only compared between siblings that form a single row or a single column. Genuine two-dimensional layouts (grid, CSS multi-column, wrapped flex) have no single correct linear order and are skipped rather than guessed.
• Elements are excluded from the reading-order comparison when they render no text, are aria-hidden, floated, position: fixed, off-canvas, or clipped to 1px, because their visual position is decoupled from source order by design. Tolerance: two boxes count as swapped only when they are fully separated along the compared axis (1px), and right-to-left containers are compared right-to-left.
• Duplicate names are only reported when the destinations differ and are observable, which today means resolved link URLs (/help and https://site/help are the same destination). Two Save submit buttons in one form are never called ambiguous, because nothing in the exposed tree says whether they do different things.
• Only elements the AI snapshot gives a ref are analyzed, and Playwright refs the elements that are visible and receive pointer events. A control that is announced but not interactable (pointer-events: none, some off-canvas widgets) is therefore skipped: without a ref it cannot be measured, so neither its aria-hidden state nor a selector to fix it can be established, and reporting it would mostly surface decorative aria-hidden icons.
• Heading levels and landmark structure are not checked; axe already reports those (heading-order, region, landmark-one-main), so use scan_page for them.
• Findings for names overlap with axe rules such as link-name, button-name and image-alt; this tool adds the quality checks (generic names, file names, label-in-name, duplicates) that axe cannot make.
• It reports the page as currently rendered. Content behind a collapsed panel or another viewport is judged in that state.

How names are measured: the AI snapshot omits a name that a control's rendered children carry (<a><strong>Docs</strong></a>, a button whose label sits in a <span>), so the audit installs its own copy of axe-core in each frame it measures and takes the accessible name axe computes there. The page's own window.axe, if any, is left as it was. Installing is bounded (10 s for the main frame, 1 s per child frame). A frame that refuses the copy (a blocking CSP, a page that removes it) is measured without names. The result says so: a WARNING: accessible names could not be measured for N of these line, elementsWithoutMeasuredName in the structured summary, and elements.unmeasuredNames in the JSON report. In those frames the snapshot's own names stand, including literal slash-delimited names such as / and /docs/, so a missing-accessible-name finding for a control named only through its children may be a false positive; treat the name findings of a run with a non-zero count as partial and confirm them by hand. A frame that times out or stops answering is not evaluated by any check: its elements are counted as unresolved (with their own warning), and if that leaves nothing evaluated the audit fails rather than report a clean page. Every read of a frame is bounded by the same budgets (10 s main frame, 1 s child frame; the lookup that tells which frame owns an element gets the larger one), so a frame that stops answering cannot hold the audit open. At most four frame operations per page stay in flight across overlapping audits; if four timed-out operations are still running, no more frame work starts and the result says where measurement stopped.

Bounds: maxElements (default 400) caps how many screen-reader-reachable accessibility tree elements are analyzed. The snapshot also refs aria-hidden subtrees, which no check reports, so measuring continues past them until the budget is filled with reachable elements (up to a hard ceiling of twice maxElements measured, so a page built mostly of hidden refs stays bounded). maxFindingsPerCheck (default 20) caps the findings listed per check. Both truncations are stated in the summary and the JSON report, and the full counts are always reported. Always writes a JSON report (default filename: audit-screen-reader-{timestamp}-{token}.json).

Example flow:

1. Navigate to the target page and let it fully load
2. Run audit_screen_reader (optionally raise maxElements for a large page)
3. Review the accessibility findings and open the generated JSON report path

Navigation Tools

browser_navigate

Navigate to a URL.

• Parameters: url (string)
• Non-2xx main-document responses are shown as an HTTP status line in page state.
• If a page opens a dialog while loading, navigation returns the pending dialog so you can resolve it with browser_handle_dialog. It does not dismiss the dialog automatically, and the interrupted response omits the page.goto replay snippet. A navigation attempt while a modal is already open fails with handling guidance. If the interrupted navigation later fails, the error appears in page console messages unless the document has changed.

browser_navigate_back

Go back to the previous page.

• If the page opens a beforeunload dialog, the tool returns the pending dialog without dismissing it. Navigation remains pending until you use browser_handle_dialog to accept leaving or dismiss it to stay on the page. While the dialog remains open, the response omits the page.goBack replay snippet. A later navigation failure appears in page console messages unless the document has changed.

browser_navigation_timeout

Set default navigation timeout for existing tabs.

• Parameters: timeout (in ms; 30000-300000)

browser_default_timeout

Set default operation timeout for existing tabs.

• Parameters: timeout (in ms; 30000-300000)

Page Interaction Tools

browser_snapshot

Capture accessibility snapshot of the current page (better than screenshot for analysis). Large data: URL payloads in snapshot output are truncated to their media type prefix. AI snapshots mark a visually present subtree excluded from accessibility queries with [aria-hidden] on its boundary element. Descendants are not marked again.

• Parameters: compress (optional boolean, default false), boxes (optional boolean; overrides snapshot.boxes for this call)
  • When compress is true, repeated non-interactive ARIA snapshot nodes are collapsed in the rendered response when a repeated structural pattern appears more than 100 times. The first 10 examples of each collapsed pattern are kept.
  • Use browser_evaluate() to retrieve the full uncompressed list when needed.
  • When boxes is true, each element includes [box=x,y,width,height] in viewport-relative CSS pixels.

browser_find

Search the current page accessibility snapshot without returning the full snapshot.

• Parameters: text (case-insensitive substring) or regex (regular expression, supports /pattern/flags), maxResults (optional positive integer; defaults to all matches), filename (optional)
• Returns matching snapshot lines with surrounding context, shown under their path from the root of the tree; ... marks truncated off-path context.
• maxResults selects the first matching lines before building context windows and preserves their ancestor paths. Context may include additional matching lines. When truncated, the header reports the total match count and (showing first Y).
• With filename, saves the same text (including no-match messages and total/truncation headers) under the same maxResults limit. Returns Saved find results as <path> and a text/plain resource link instead of inline search results. Without filename, the response is unchanged.
• Filenames follow this server's artifact policy: sanitized names contained in the configured output directory, with existing files rejected. Unlike upstream Playwright MCP, paths are not resolved against the workspace root.

browser_click

Perform click on a web page element.

• Parameters: element (description), ref (element reference), doubleClick (optional)

browser_type

Type text into editable element.

• Parameters: element, ref, text, submit (optional), slowly (optional)

browser_hover

Hover over element on page.

• Parameters: element, ref

browser_drag

Perform drag and drop between two elements.

• Parameters: startElement, startRef, endElement, endRef

browser_drop

Simulate an external drag and drop of files or clipboard-like data onto an element, for testing drop zones that never see a drag start inside the page.

• Parameters: element, ref, paths (optional array of absolute file paths), data (optional map of mime type to value, e.g. {"text/plain": "hello"})
• At least one of paths or data is required.
• Fails if the target's dragover handler does not accept the payload.
• paths are read from the filesystem of the machine running the server, exactly as browser_file_upload does, and a relative path resolves against the server's working directory. Unlike browser_file_upload this needs no file chooser to be open, so any page with a dragover handler is a valid target — treat it as a tool that can hand local file contents to the page.

browser_select_option

Select an option in a dropdown.

• Parameters: element, ref, values (array)

browser_fill_form

Fill multiple fields with one call. Generated Playwright code preserves checkbox/radio booleans and selects combobox options by label, matching the performed action.

• Parameters: fields (array of objects with name, type, ref, and value)

browser_press_key

Press a key on the keyboard.

• Parameters: key (e.g., 'ArrowLeft' or 'a')
• Keys are delivered by Playwright's US keyboard layout. On the pinned Playwright 1.63.0, some numpa