A11y Mcp

A11y MCP Server

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!

Features

• Perform detailed accessibility audits on any webpage
• Get a summary of accessibility issues
• Filter audits by specific WCAG criteria
• Include HTML snippets in the results for easier debugging

Installation

# Install globally
npm install -g a11y-mcp

# Or use directly with npx
npx a11y-mcp

Configuration

To use this MCP server with Cline, you need to add it to your MCP settings configuration file.

MCP configuration

Add the following to the mcpServers object:

{
  "mcpServers": {
    "a11y": {
      "command": "npx",
      "args": ["a11y-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools

audit_webpage

Performs a detailed accessibility audit on a webpage.

Parameters:

• url (required): URL of the webpage to audit
• includeHtml (optional): Whether to include HTML snippets in the results (default: false)
• tags (optional): Array of specific accessibility tags to check (e.g., wcag2a, wcag2aa, wcag21a, best-practice)

Example:

Use the a11y MCP server to audit example.com for accessibility issues

get_summary

Gets a summary of accessibility issues for a webpage.

Parameters:

• url (required): URL of the webpage to audit

Example:

Give me an accessibility summary of example.com

Example Usage

Once configured, you can ask Claude to use the MCP server to perform accessibility audits:

1. "Can you check example.com for accessibility issues?"
2. "Audit my website at https://mywebsite.com for WCAG 2.1 AA compliance"
3. "Give me a summary of accessibility issues on https://example.com"
4. "Check if my local development server at http://localhost:3000 has any critical accessibility problems"

Development

To run the server locally for development:

npm start

Releasing

This project includes a release script to help with versioning and publishing to npm. The script handles version bumping, running tests, git tagging, and npm publishing.

To release a new version:

# Make sure the script is executable
chmod +x release.sh

# Release a patch version (default)
./release.sh

# Release a minor version
./release.sh --minor

# Release a major version
./release.sh --major

# Release a specific version
./release.sh --version=1.2.3

# Skip git operations
./release.sh --skip-git

# Dry run (no changes will be made)
./release.sh --dry-run

# Force release even with uncommitted changes
./release.sh --force

For more information, run:

./release.sh --help

License

MPL 2.0

Credits

This project builds atop the awesome work done by axe-core

Security and hosting

Requires Node.js 22.12 or newer. Chrome runs with its sandbox enabled. Every HTTP(S) connection, including redirects and subresources, goes through a validating proxy that pins the destination IP. Private, link-local, multicast, reserved, and cloud metadata addresses are blocked, including mapped IPv6. Loopback remains available for local development; set AUDIT_ALLOW_LOOPBACK=false for public-only audits. LAN addresses are no longer supported. One audit runs per MCP process, with a 90-second browser deadline. For hosted use, additionally isolate browser workers and enforce network egress restrictions at the infrastructure layer. Automated axe checks do not establish WCAG conformance; manual review is still required.

Run npm test, npm run test:smoke (requires Chrome), and npm audit.

Maintainer CI and releases

GitHub Actions runs the build, network and release-policy tests, npm security audit, and real Chrome smoke tests on the minimum supported Node version and Node 24. Node 24 also installs the npm tarball in a clean temporary project and checks its executable, dependencies, MCP version, and browser audits.

Every push to main runs the release pipeline. When package files change, it automatically increments the patch version (or honors a larger version already committed), synchronizes package metadata, repeats validation, commits and tags the release, publishes to npm with provenance, and creates a GitHub release. Changes limited to documentation, tests, or workflows do not publish a new version. Runtime server versions come from package.json.

Dependabot checks npm and GitHub Actions weekly. A successful PR CI run automatically merges npm updates only when all existing changed dependencies are stable patch/minor upgrades and only package.json / package-lock.json changed. Major upgrades, 0.x minor upgrades, downgrades, prereleases, and GitHub Actions changes require review. The merge job runs only trusted code from main, verifies the tested PR head, and explicitly dispatches publishing after a bot merge.

npm publishing uses the npm GitHub environment and an npm trusted publisher for priyankark/a11y-mcp, workflow publish.yml, environment npm, with direct publishing allowed. No npm token is stored in GitHub. The environment accepts deployments only from main.

To retry a failed release, rerun the Publish workflow or run ./release.sh. The pipeline reuses an unpublished version and skips an already published, unchanged package. If a reserved release tag points to different code, it stops rather than overwriting that version. For a breaking change, update package.json and package-lock.json to the intended major/minor version in the reviewed PR before merging.