# axe-devtools-mcp

An [MCP](https://modelcontextprotocol.io) server that runs [axe-core](https://www.npmjs.com/package/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:
  ```bash
  npx playwright install chromium
  ```

## Use with Claude Code

Register the server with the Claude Code CLI:

```bash
# 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:

```json
{
  "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:

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

### Cursor

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

```json
{
  "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

```bash
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

```bash
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