a11y-mcp-server

An MCP server that exposes axe-core accessibility auditing as tools — so any MCP-compatible agent (Claude Desktop, Claude Code, or any other MCP client) can audit HTML without a project-specific integration.

This grew out of agentic-design-tools's a11y-review Claude Code skill: the skill is Claude Code-specific, this is the same auditing capability as a standard protocol server any agent can call.

Tools

Tool	Description
audit_html	Audit an inline HTML string
audit_file	Audit a local .html file by path
audit_url	Fetch a URL and audit the raw (server-rendered) response HTML

Each accepts an optional tags array to restrict which axe-core rule tags run, e.g. ["wcag2a", "wcag2aa"].

Scope note: audits run via jsdom, which has no real layout engine. That reliably catches structural/semantic issues — missing alt text, unlabeled form inputs, missing lang/<title>, empty link text, and similar — but rules that depend on rendered geometry or computed color (color-contrast, focus-order checks) won't reliably fire. For full WCAG coverage, run axe-core in a real browser (Playwright/Puppeteer) against the rendered page.

Security note: audit_html and audit_url execute any <script> in the input inside a sandboxed jsdom window (no Node.js API access). Only audit HTML/URLs you trust.

Install & configure

npm install -g @aiuxmasters/a11y-mcp-server

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "a11y": {
      "command": "npx",
      "args": ["-y", "@aiuxmasters/a11y-mcp-server"]
    }
  }
}

Programmatic API

import { auditHtml } from "@aiuxmasters/a11y-mcp-server";

const result = await auditHtml("<img src='logo.png'>");
console.log(result.violations); // [{ id: "image-alt", impact: "critical", ... }]

Development

npm install
npm test        # unit tests + a real end-to-end MCP client/server round trip over InMemoryTransport
npm run build

License

MIT — see LICENSE.