Automate Web Accessibility with AI | navable MCP

Automated accessibility tests can run during development. navable connects axe-core scans with fix plans that an AI coding agent can work through in the editor.

Explore the criteria in the WCAG hub, follow the Developer Workflows or start with the Accessibility Audit.

Scan, plan, fix and verify

The MCP server supplies technical findings. Agent skills structure the next steps: create a plan, edit the code and scan again. Review proposed changes in code review and manual tests; an AI agent can make mistakes.

1. @navable/mcp — An MCP Server for Accessibility Scanning

The Model Context Protocol (MCP) is an open standard that lets AI coding agents call external tools. Our MCP server connects your agent to a real Chromium browser running axe-core, the industry-standard accessibility testing engine.

It provides three tools:

• run_accessibility_scan — Scans a URL against WCAG 2.1 Level A + AA rules. Returns structured violations with severity, affected elements, WCAG success criteria, and EN 301 549 clause mapping.
• generate_fix_plan — Converts scan results into a prioritized .navable-plan.json file. Critical issues first, minor items last. Each entry includes the rule violated, affected nodes, and a fix description.
• update_fix_status — Tracks progress as items move from pending to done. The plan file becomes a living document your team can reference.

Works with Cursor, VS Code (GitHub Copilot), and Claude Code.

npm: @navable/mcp | GitHub: web-DnA/navable-web-accessibility-mcp

2. navable Agent Skills — Workflow Instructions for AI Coding Agents

Agent skills are structured instructions that teach AI agents specific workflows. Copy them into your project from the GitHub repository. Ours cover four scenarios:

The scan skill includes 10 fix guides covering images, forms, color contrast, ARIA, keyboard navigation, headings, landmarks, language, navigation, and tables — with before/after code examples for 55 common violations.

GitHub: web-DnA/navable-web-accessibility-skills

Example: Keyboard access to scrollable code blocks

Two horizontally scrollable code blocks on our MCP tool page could not be reached with a keyboard. A local scan with @navable/mcp 0.2.0, axe-core 4.13.0 and Playwright 1.64.0 reported the scrollable-region-focusable rule for them. The scan covered the #how-it-works section.

run_accessibility_scan({
  url: "http://localhost:3002/de/tools/accessibility-mcp-fuer-ai-agents",
  include: ["#how-it-works"]
})

Pass the returned scanId to generate_fix_plan. Our run created fix-1 for this rule. The fix changed the existing code blocks:

// Before
<pre className="bg-muted p-3 rounded-lg text-xs overflow-x-auto">
  <code>{step.code}</code>
</pre>

// After
<pre tabIndex={0} className="bg-muted p-3 rounded-lg text-sm overflow-x-auto">
  <code>{step.code}</code>
</pre>

With tabIndex={0}, you can reach the block with Tab and use arrow keys to read the overflowing content. The font was also increased to the project’s minimum size. Check keyboard operation and visible focus in the browser as well.

Repeating the scan on the same section found no remaining scrollable-region-focusable violation. That verifies this fix in the tested state, not accessibility across the entire page. Mark the verified plan item as done with update_fix_status.

If the plan cannot be written

First check NAVABLE_PROJECT_ROOT: the server needs to know which project contains .navable-plan.json. In our version 0.2.0 test, plan generation for the full-page scan also failed on nested selectors from the video player. A scan of the affected section could be converted into a plan. Limit the scan only to investigate the error; the other content still needs its own evaluation.

The first call may download the package and Chromium, so we do not promise a fixed setup time. If the automatic browser download fails, follow the MCP installation instructions.

The local loop checks edits during development. A CI test runs on push or pull request and needs a running test server and a defined test path. Hosted MCP retrieves existing navable audit data. The MCP tool page covers setup and rule selection; Developer Workflows explains how the paths fit together.

How It Works in Practice

The skills specify the steps and the MCP server supplies scan data. At each step, check that findings and proposed changes fit the page being tested.

A developer starts their dev server and types into their IDE:

Scan http://localhost:3000 for accessibility issues

Here's what that looks like in practice:

Step 1: Real Browser Scan

The MCP server launches headless Chromium, navigates to the URL, and runs axe-core. This tests the actual rendered page — JavaScript-generated content, dynamic components, CSS-driven visibility — not just static HTML.

Step 2: Structured Results

Every violation comes back with:

• Severity level — critical, serious, moderate, or minor
• CSS selectors + HTML snippets — pointing to the exact affected elements
• WCAG success criterion — e.g., 1.4.3 Contrast (Minimum)
• EN 301 549 clause — e.g., §9.1.4.3 — mapping to the technical standard

Step 3: Fix Plan Generation

The agent creates .navable-plan.json — a structured, priority-sorted fix plan. Each item tracks:

{
  "id": "fix-1",
  "ruleId": "color-contrast",
  "impact": "serious",
  "wcagSc": ["1.4.3"],
  "en301549": "§9.1.4.3",
  "help": "Elements must meet minimum color contrast ratio thresholds",
  "status": "pending"
}

Step 4: Guided Fixes

The agent loads the relevant fix guide, locates the source file using the CSS selector and HTML snippet from the scan, applies the code change, and marks the item as done. It moves through the plan in priority order — critical first, minor last.

Step 5: Verification

After fixes are applied, the agent re-scans the page to confirm violations are resolved. The plan file records a verification timestamp for audit documentation.

The full cycle — scan, plan, fix, verify — takes minutes. Not days.

The EN 301 549 Mapping (and Why It Matters)

The mapping relates technical findings to WCAG success criteria and EN 301 549 clauses. It helps organise and document fixes. It does not assess every requirement in the standard or the legal duties of a service.

Setup in Under 2 Minutes

For VS Code (GitHub Copilot)

Create .vscode/mcp.json:

{
  "servers": {
    "navable": {
      "command": "npx",
      "args": ["-y", "@navable/mcp"]
    }
  }
}

For Cursor

Create .cursor/mcp.json:

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

For Claude Code

claude mcp add navable -- npx -y @navable/mcp

The package installs via npx. Chromium downloads automatically on first scan (~150 MB one-time). This setup requires neither an API key nor an account.

To add agent skills, copy the skills folder into your project:

# VS Code
cp -r skills/* .github/skills/

# Cursor
cp -r skills/* .agents/skills/

# Claude Code
cp -r skills/* .claude/skills/

What Gets Tested

The scanner checks machine-evaluable axe-core rules in these categories:

The fix guides contain before/after code for 55 documented patterns. Check whether the proposed fix fits your element.

Built-In Reference Resources

The MCP server also exposes reference documentation as MCP resources:

• WCAG ↔ EN 301 549 mapping — full cross-reference table with testability ratings
• Fix patterns by rule — request specific patterns by axe rule ID (e.g., navable://docs/fix-patterns/color-contrast,label)
• ARIA patterns — 25 WAI-ARIA APG widget patterns with keyboard requirements
• Semantic HTML reference — HTML elements mapped to implicit ARIA roles

These load on demand and keep the agent's context focused on what's relevant to the current fix.

What It Doesn't Replace

axe-core detects machine-evaluable structure, attribute, contrast and ARIA issues. Manual testing is needed for:

• Keyboard navigation flow quality
• Screen reader announcement order and clarity
• Cognitive load and content readability
• Whether alt text is actually meaningful
• Complex interaction patterns in context

navable handles the automatable portion so your team can focus manual testing time on the things only humans can evaluate. Record which criteria still need manual review.

Privacy and Security

Local MCP starts Chromium and the scan on your machine. Your AI client handles prompts and tool results according to its own settings; depending on the provider, these may go to an AI service. Check those settings before testing confidential content. The MCP package is open source and MIT-licensed.

Who This Is For

• Developers who want accessibility feedback in their editor while they build, not in a PDF weeks later
• Team leads looking to make accessibility a continuous part of development instead of a periodic audit
• Compliance teams who need EN 301 549 mapping for BFSG documentation
• Agencies finding technical barriers early in client projects

Get Involved

Local MCP is developed as an open-source package. If you run into issues, have feature requests, or want to contribute fix patterns:

• Open an issue on GitHub
• Star the repos if you find them useful
• PRs welcome — especially for additional fix patterns and ARIA guides

Links:

• MCP Server: github.com/web-DnA/navable-web-accessibility-mcp
• Agent Skills: github.com/web-DnA/navable-web-accessibility-skills
• npm: @navable/mcp

Explore the development workflow and Audit.

Use the website testing checklist to decide which user journeys to re-test after a code fix.