vinnyang/axe-scanner-mcp

Axe Scanner MCP Server

A standalone Model Context Protocol server that runs axe accessibility scans for a supplied URL using Playwright.

Screenshot

Prerequisites

• Node.js 18 or newer
• Playwright browsers (npx playwright install), plus system dependencies if required (npx playwright install --with-deps on macOS/Linux)

Installation

npm install
npm run build

Setting up with MCP Clients

This configuration works with all MCP-compatible clients (Claude Desktop, Cursor, etc.). Add the following to your MCP client configuration:

Using node:

{
  "mcpServers": {
    "axe-scanner-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/axe-scanner-mcp/dist/index.js"]
    }
  }
}

Using npx:

{
  "mcpServers": {
    "axe-scanner-mcp": {
      "command": "npx",
      "args": ["-y", "/absolute/path/to/axe-scanner-mcp"]
    }
  }
}

Note:

• Use absolute paths in your configuration
• Configuration file locations:
  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
  • Cursor: Settings → Features → Model Context Protocol
• Restart your MCP client after adding the server configuration

Usage

Running the MCP Server

You can run the server in several ways:

Using npm scripts (recommended for development):

npm start

Or run in development mode with automatic restart on file changes:

npm run dev

The dev script watches for changes in the source files and automatically restarts the server.

Using npx:

After building the package (npm run build), you can run it with npx:

# Using the local path
npx /absolute/path/to/axe-scanner-mcp

# Or link it locally first for easier access
npm link
npx axe-scanner-mcp

# Or install it in another project
npm install /absolute/path/to/axe-scanner-mcp
npx axe-scanner-mcp

Using node directly:

node dist/index.js

Run a one-off scan from the CLI:

npm run scan -- https://example.com

Registered tool

axe_scan_url Runs an axe accessibility scan and returns both a summary and the full axe results JSON.

Input arguments:

• url (string, required): Page to scan.
• tags (string[], optional, defaults to ["wcag2a"]): Restrict analysis to specific tags. Leave empty to disable tag filtering.
• runOnlyRules (string[], optional): Restrict analysis to specific rule IDs. Cannot be combined with tags.
• disableRules (string[], optional): Skip specific rule IDs.
• includeSelectors (string[], optional): CSS selectors to scope the scan.
• excludeSelectors (string[], optional): CSS selectors to omit from the scan.
• waitUntil ("load" | "domcontentloaded" | "networkidle" | "commit", optional): Navigation lifecycle to await. Defaults to load.
• navigationTimeoutMs (number, optional): Playwright navigation timeout in milliseconds.
• legacyMode (boolean, optional): Whether to run axe in legacy mode to avoid blank-page aggregation (disables cross-origin frame testing).
• viewport (object, optional): Override viewport width, height, deviceScaleFactor, and/or userAgent. Defaults to 1280×720 / DPR 1 / Playwright default UA.
• browser ("chromium" | "firefox" | "webkit", optional): Browser engine to launch. Defaults to chromium.
• headless (boolean, optional): Run the browser in headless mode. Defaults to true.
• postNavigationWaitMs (number, optional): Milliseconds to wait after navigation (and optional selector wait) before running axe. Defaults to 1000.
• waitForSelector (string, optional): CSS selector to wait for before the post-navigation delay.
• axeOptions (object, optional): Raw options passed to axe.configure via builder.options(...).
• includeSummary (boolean, optional): When true, adds a short human-readable summary string alongside the full JSON payload. Defaults to false.

Development

Development mode with watch:

The dev script automatically watches for file changes and restarts the server:

npm run dev

Manual rebuild:

To rebuild the project manually:

npm run build

Format of the tool response:

• success: indicates execution status.
• url: scanned URL.
• summary: counts of violations, passes, incomplete, and inapplicable rule results.
• analysis: raw axe results returned by @axe-core/playwright.