axe-devtools-mcp

An MCP server that runs axe-core accessibility audits and returns the results to any MCP client — including Claude Code, Claude Desktop, and Cursor.

It renders pages in headless Chromium (via Playwright), injects axe-core, and reports WCAG violations with impact levels, affected elements, and fix guidance.

Tools

Tool	Description
scan_url	Load a URL (live site or local dev server) in headless Chromium and run an axe-core audit.
scan_html	Run an axe-core audit against a raw HTML string.
scan_file	Scan a local .html file on disk (loaded via file:// so linked CSS/assets resolve). Good for static-site build output.
scan_site	Crawl a running site breadth-first from a start URL, following same-origin links, and audit every page (up to maxPages). Returns an aggregated report plus per-page detail.

Both tools accept:

• tags — WCAG / rule tags to run, e.g. ["wcag2a", "wcag2aa", "wcag21aa", "best-practice"]
• rules — only run these axe rule ids, e.g. ["color-contrast", "image-alt"]
• excludeRules — axe rule ids to skip
• detail — "full" (default; lists offending elements + fixes) or "summary" (rule + counts only)
• maxNodes — max offending elements to list per rule when detail="full" (default 5)
• includeIncomplete — also report axe "incomplete" items: checks that need manual review (e.g. color-contrast over background images, aria-hidden focus). Off by default; set true to surface likely issues that automated rules could not confirm.

scan_url and scan_file also accept include (CSS selector to scope the scan) and timeoutMs. scan_file takes a path (absolute, or relative to the server's working directory). scan_site additionally takes maxPages (default 5, max 50) and sameOriginOnly (default true).

Scanning your own site / codebase

axe-core is a runtime engine — it audits the rendered DOM, not your source files. To audit code you're building:

• Running app (best): start your dev server (npm run dev), then scan_url http://localhost:3000/..., or scan_site http://localhost:3000 to crawl every route in one call. This tests exactly what users get after your framework renders.
• Static build output: scan_file ./dist/index.html. Note single-page-app builds are usually empty shells hydrated by JS, so scan the running server instead.
• Source-level linting (a different, complementary tool): eslint-plugin-jsx-a11y, eslint-plugin-vuejs-accessibility, etc.

Requirements

• Node.js >= 18
• A Chromium browser managed by Playwright. npm install runs npx playwright install chromium automatically; if that was skipped, run it manually:

  npx playwright install chromium
  

Use with Claude Code

Register the server with the Claude Code CLI:

# From npm (once published)
claude mcp add axe-devtools -- npx -y axe-devtools-mcp

# Or from a local clone
claude mcp add axe-devtools -- node /absolute/path/to/axe-devtool-mcp/dist/index.js

Then in Claude Code:

Scan https://example.com for accessibility issues.

Use with other MCP clients

This is a standard stdio MCP server, so it works in any MCP-capable client. Once published to npm, every client uses the same npx invocation; before publishing, replace it with node /absolute/path/to/axe-devtool-mcp/dist/index.js.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart the app:

{
  "mcpServers": {
    "axe-devtools": {
      "command": "npx",
      "args": ["-y", "axe-devtools-mcp"]
    }
  }
}

VS Code / GitHub Copilot (Agent mode)

Add a .vscode/mcp.json in your workspace (note the servers key), then enable it from the Copilot Chat "Tools" picker in Agent mode:

{
  "servers": {
    "axe-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "axe-devtools-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "axe-devtools": {
      "command": "npx",
      "args": ["-y", "axe-devtools-mcp"]
    }
  }
}

Tip: some clients (e.g. background/headless runners) don't run npm lifecycle scripts, so the Chromium auto-install won't fire. If a scan fails to launch a browser, run npx playwright install chromium once on that machine.

Run from source

git clone https://github.com/Ravindrabisht12/axe-devtool-mcp.git
cd axe-devtool-mcp
npm install
npm run build
node dist/index.js   # speaks MCP over stdio

Publish to npm

npm login
npm publish --access public

After publishing, anyone can run it with npx -y axe-devtools-mcp — no clone required.

How it works

MCP client (Claude Code)
   │  stdio (JSON-RPC)
   ▼
axe-devtools-mcp  ──►  Playwright (headless Chromium)  ──►  axe-core injected into the page
   ▲                                                              │
   └──────────────  formatted violations + fixes  ◄──────────────┘

License

MIT