Skip to main content
Glama

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.

Related MCP server: A11y MCP Server

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

Available Tools

4 tools
scan_fileScan a local HTML file for accessibility issuesA

Runs an axe-core accessibility audit against a local .html file on disk (loaded via file:// so linked CSS/assets resolve). Use for static-site build output. Note: single-page-app build files are usually empty shells hydrated by JS — scan the running dev server with scan_url instead.

Inputs: path (required), tags, rules, detail, +5 more.

scan_htmlScan raw HTML for accessibility issuesA

Runs an axe-core accessibility audit against a raw HTML string (rendered in headless Chromium). Use for markup snippets or generated HTML that isn't served at a URL.

Inputs: html (required), tags, rules, detail, +3 more.

scan_siteCrawl a running site and scan multiple pagesA

Crawls a running site breadth-first starting from a URL, following same-origin links, and runs an axe-core audit on each page (up to maxPages). Returns an aggregated report plus per-page detail. Use to audit a whole site/app in one call instead of scanning routes one by one.

Inputs: url (required), tags, rules, detail, +6 more.

scan_urlScan a URL for accessibility issuesA

Loads a URL in headless Chromium, runs an axe-core accessibility audit, and returns WCAG violations with fix guidance. Use for live pages (http/https) or local dev servers.

Inputs: url (required), tags, rules, detail, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct input type (file, HTML string, live URL, whole site crawl), leaving no ambiguity about which to use.

    Naming Consistency5/5

    All tools follow a consistent 'scan_<target>' pattern, making the naming predictable and intuitive.

    Tool Count5/5

    With 4 tools, the set covers the main use cases for accessibility auditing without being excessive or insufficient.

    Completeness5/5

    The tools provide a complete workflow for auditing static files, HTML snippets, single pages, and entire sites, with no obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      An MCP (Model Context Protocol) server for performing accessibility audits on webpages using axe-core. Use the results in an agentic loop with your favorite AI assistants (Cline/Cursor/GH Copilot) and let them fix a11y issues for you!
      2
      592 npm
      53
      Mozilla Public 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A lightweight local MCP server that runs axe-core accessibility audits via Playwright and returns compressed, actionable results optimized for Claude's context window.
      5
      15 npm
      MIT