MCP无障碍扫描

Installation

You can install the package using any of these methods:

Using npm:

npm install -g mcp-accessibility-scanner

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 .

Docker smoke test

npm run test:docker

Interactive route (no setup)

Every tool shares one browser context, and audit_site crawls in a temporary tab of that same context, so cookies and local storage created while you drive the browser are already 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

This works out of the box in every mode, including the default persistent-profile mode. With the default profile the session 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.

Screenshot & Visual Tools

#### browser_take_screenshot Take a screenshot of the current page. - Parameters: filename (optional), type (png, jpeg, or webp), scale (css or device, default css), fullPage (optional), element/ref pair (for element screenshots) - scale: device captures a high-resolution screenshot using device pixels (accounts for the device pixel ratio); scale: css keeps the image sized in CSS pixels.

#### browser_pdf_save Save page as PDF. - Parameters: filename (optional, defaults to page-{timestamp}-{token}.pdf)

This tool requires --caps pdf in the CLI.

#### browser_install Install the configured browser engine (use when browser executable is missing). - Parameters: none

Configuration

Here's the Claude Desktop configuration:

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

Advanced Configuration

You can pass a configuration file to customize Playwright behavior:

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

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
  },
  "network": {
    "allowedOrigins": ["example.com", "trusted-site.com"],
    "blockedOrigins": ["ads.example.com"]
  },
  "snapshot": {
    "boxes": true
  }
}

Available Options:

• browser.browserName: Browser to use (chromium, firefox, webkit)
• 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.launchOptions.chromiumSandbox: Defaults to false for downloaded Chromium builds on Linux because they lack the setuid sandbox helper, and true otherwise. Remote and VS Code endpoints choose on the remote host. An explicit config or PLAYWRIGHT_MCP_SANDBOX value wins; --no-sandbox always disables it. - browser.cdpEndpoint: Attach to an already-running Chromium-family app with CDP enabled - browser.cdpHeaders: Map of HTTP headers to send with the CDP connect request, e.g. { "Authorization": "Bearer <token>" }, for endpoints that require header-based authentication - browser.cdpTimeout: Maximum time in milliseconds to wait when connecting to the CDP endpoint (default: 30000) - browser.cdpLaunch: Launch a Chromium-family desktop app with CDP enabled, wait for the endpoint, and manage the child process lifecycle - CDP attach modes preserve the target browser's existing default-context settings instead of applying Playwright's defaults. - browser.contextOptions.storageState: Start each session from a recorded Playwright storage state; applied in every mode except --extension (fresh contexts receive it at creation, reused contexts via setStorageState()). Sessions that share one reused context (non-isolated CDP modes) get the state applied once per context — a session joining a live context inherits its current state, not a fresh copy of the file; see Auditing pages behind a login - browser.profileDirName: Chrome profile directory name used in extension mode, for example Default or Profile 1 (CLI: --profile-dir-name, env: PLAYWRIGHT_MCP_PROFILE_DIR_NAME). Requires --user-data-dir and extension mode (--extension or --connect-tool); defaults to the last-used profile that has the extension installed. - timeouts.navigationTimeout: Maximum time for page navigation in milliseconds (default: 60000) - timeouts.defaultTimeout: Default timeout for Playwright operations in milliseconds (default: 5000) - timeouts.settle: How long to wait after every action before responding (default: 500). An action that finishes quietly is first watched for up to 100ms (or the settle delay, whichever is shorter) so scheduled network work can still be awaited before the settle delay. - network.allowedOrigins: List of origins to allow (blocks all others if specified) - network.blockedOrigins: List of origins to block - snapshot.boxes: Include each element's viewport-relative bounding box as [box=x,y,width,height] in snapshots (default: false; CLI: --snapshot-boxes, env: PLAYWRIGHT_MCP_SNAPSHOT_BOXES=1) - server.authToken: When set, Streamable HTTP requests (--port) require Authorization: Bearer <token> or return 401 (env: PLAYWRIGHT_MCP_AUTH_TOKEN). Blank or malformed tokens fail at startup. The scheme is case-insensitive; the token is exact. Bearer auth does not encrypt traffic: authenticated listeners must bind to loopback, such as --host 127.0.0.1; use a TLS reverse proxy for remote access. The printed client config includes a header placeholder to replace locally, without logging the secret. Unset keeps unauthenticated access. - outputDir: Directory for output files — reports, screenshots, traces, and session logs (CLI: --output-dir, env: PLAYWRIGHT_MCP_OUTPUT_DIR). Defaults to a fresh directory under the system temp folder, resolved once per server run so all of a run's artifacts land together. The output location is always server configuration; the deprecated MCP roots capability (client workspace folders) is no longer consulted.

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.

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.

Caller-supplied screenshot, PDF, 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.

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.

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 — the tool list is advertised as cacheable for one hour with cacheScope: "private" — 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 initialize keep the classic Mcp-Session-Id 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".

CLI Modes

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

Browser extension mode

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

npx 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.

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":["mcp-accessibility-scanner"]}'

For VS Code Insiders:

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