Navable MCP
Navable MCP
Part of navable.io — open-source accessibility tools for development teams.
A Model Context Protocol (MCP) server that gives AI coding agents real-browser accessibility scanning. Scans localhost pages with Playwright + axe-core (and optionally Pa11y/HTMLCS as a second engine), returns WCAG 2.1 Level A + AA violations with EN 301 549 mapping, and generates structured fix plans your agent can work through autonomously.
Quick Start
Add the MCP config for your editor (see below)
Start your dev server
Ask your agent: "scan http://localhost:3000 for accessibility issues"
Chromium installs automatically on the first scan (~150 MB one-time download). No extra step needed. If auto-install fails (e.g. restricted network), install manually:
npx playwright install chromium
Related MCP server: Accessibility MCP Server
MCP Configuration
Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"navable": {
"command": "npx",
"args": ["-y", "@navable/mcp"],
"env": {
"NAVABLE_PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
}NAVABLE_PROJECT_ROOT is optional. Set it if .navable-plan.json is written to the wrong directory
(some IDE extension hosts use a different working directory). Omit env if auto-detection works.
VS Code (Copilot)
Add to .vscode/mcp.json:
{
"servers": {
"navable": {
"command": "npx",
"args": ["-y", "@navable/mcp"]
}
}
}Claude Code
claude mcp add navable -- npx -y @navable/mcpAvailable Tools
run_accessibility_scan
Scans a URL for WCAG 2.1 Level A + AA accessibility violations.
By default, only axe-core runs. Pa11y/HTMLCS is opt-in — see
enginesbelow.
Input | Description |
| Full URL to scan (e.g. |
| axe-core rule tags to include (optional) |
| CSS selectors to limit scan scope (optional) |
| CSS selectors to exclude (optional) |
| Engines to run. Default: |
|
|
Workflow: The response includes a scanId. Pass it to generate_fix_plan instead of
pasting the full scan object — this avoids MCP client serialization issues and keeps chats smaller.
generate_fix_plan
Converts scan output into a structured AccessibilityFixPlan and writes .navable-plan.json when
writeToDisk is true.
Input | Description |
| From |
| Full scan JSON (fallback if the server was restarted; only the last 10 scans are cached) |
| Write |
|
|
Returns planPath (absolute) when the file is written successfully. On write failure, returns an
error with the attempted path; set NAVABLE_PROJECT_ROOT in the MCP server env if needed.
update_fix_status
Mark fix plan items as done, skipped, or in progress. Prefer this over hand-editing
.navable-plan.json.
Input | Description |
| Item ID(s), e.g. |
|
|
| Absolute path to plan file (optional; defaults to project root) |
Returns updated progress summary (total, done, pending, skipped).
Available Resources
Resources use text/markdown. Prefer parameterized URIs during fix workflows to save context.
WCAG / compliance
URI | Size (typical) | Description |
| Compact | WCAG SC → EN 301 549 → testability → axe rules; summary stats; WCAG 2.2 forward-looking table |
| Large | BFSG legal context: scope, German glossary, enforcement, BITV 2.0, dates (optional) |
Fix patterns (axe rule → before/after code)
URI | Size (typical) | Description |
| Small | Preferred. Comma-separated axe rule IDs, no spaces. Example: |
| Large (~49 KB) | All 55 documented rules |
ARIA (WAI-ARIA APG patterns)
URI | Size (typical) | Description |
| Compact index | Table: slug, name, complexity, short description |
| Per pattern | Full detail (e.g. |
Semantic HTML
URI | Size (typical) | Description |
| Compact index | Table: element, implicit role, short description |
| Per element | Full detail (e.g. |
Configuration
Create a .navable.json in your project root to customize behavior:
{
"allowedHosts": ["localhost", "127.0.0.1", "[::1]"],
"timeout": 15000,
"waitUntil": "load",
"axeTags": ["wcag2a", "wcag21a", "wcag2aa", "wcag21aa"],
"axeDisableRules": [],
"engines": ["axe"],
"htmlcsIgnore": [],
"wcagLevel": "AA"
}Option | Default | Description |
|
| Hostnames the scanner may reach |
|
| Navigation timeout in ms |
|
| Playwright wait strategy ( |
|
| axe-core tags to include |
|
| axe-core rule IDs to skip |
|
| Engines to run. Add |
|
| HTMLCS codes to suppress (see Pa11y / HTMLCS noise reduction below) |
|
| Target WCAG conformance level |
Pa11y / HTMLCS as a second engine
Pa11y does not run by default. A plain run_accessibility_scan({ url }) call — and the default
agent workflow — uses axe-core only. Pa11y/HTMLCS runs only when you opt in via the engines
parameter or .navable.json.
When to use both engines
Use case | Recommended |
Iterative fix loops (scan → fix → re-scan) |
|
One-shot compliance audit / BFSG / EN 301 549 sign-off |
|
User explicitly asks for thorough / dual-engine scan |
|
How to enable Pa11y
Per scan — pass engines to the tool:
run_accessibility_scan({ url: "http://localhost:3000", engines: ["axe", "htmlcs"] })Always on — add to .navable.json in your project root:
{
"engines": ["axe", "htmlcs"]
}How results change with both engines
When engines includes "htmlcs", Pa11y runs in parallel with axe-core and shares Playwright's
Chromium binary (no extra download). Crossover findings are deduped server-side with a deliberate
bias toward false negatives over false positives — ambiguous matches are kept as separate entries
rather than collapsed. The dedup uses a confidence ladder, all gated on same WCAG SC:
Full selector match (after normalizing
html > body >prefixes and whitespace) + loose HTML compare (200-char prefix, whitespace-collapsed, lowercased).Strict suffix match — one selector is the tail of the other, with
>immediately before the boundary (e.g. axesection:nth-child(3) > pmatches HTMLCS#root > main > section:nth-child(3) > p) + loose HTML compare.Attribute-stripped suffix match (axe
button[type="button"]vs HTMLCSbutton) + strict (full-string) HTML equality. Distinct elements likeinput[type="checkbox"]andinput[type="radio"]collapse to the same stripped selector, so HTML must match exactly.Last-3-segment fingerprint match + positional discriminator (
:nth-,#id,.class, or[…]somewhere in the fingerprint) + loose HTML compare. The discriminator gate prevents false merges in repeating layouts (ul > li > alists, grids).
Survivors:
Crossover-confirmed: kept as the axe entry, tagged with
alsoFlaggedBy: ["htmlcs"].HTMLCS-only: kept with
source: "htmlcs", plushelpUrl(WCAG Understanding doc) and a one-sentencedeveloperNoteto give agents enough context to act on the cryptic HTMLCS codes.
Same-element overlaps under different WCAG criteria are kept separate. axe and HTMLCS often map the same element to different success criteria (e.g. a
<select>with no label may surface as SC 3.3.2 and SC 4.1.2 and SC 1.3.1). Each is a real audit finding and dedup never collapses across SCs — that would lose traceability for compliance reporting. Thescan-accessibilityandfix-accessibilityskills include guidance to group plan items by DOM element so the agent applies one HTML edit per element, then marks all related fix IDs resolved at once. Without this grouping, an agent may edit the same element repeatedly and risk one fix undoing another.
HTMLCS often emits advisory "Check that…" warnings intended for human auditors. They aren't useful
for an AI agent and inflate token cost. Suppress them via htmlcsIgnore. Common candidates:
{
"engines": ["axe", "htmlcs"],
"htmlcsIgnore": [
"WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.AlignAttr",
"WCAG2AA.Principle2.Guideline2_4.2_4_1.H64.1",
"WCAG2AA.Principle1.Guideline1_3.1_3_1.H42.2"
]
}Find more codes to suppress in your scan output — any HTMLCS id whose help text starts with
“Check that…” is a likely candidate.
Set NAVABLE_PROJECT_ROOT in the MCP server environment (see Cursor example above) so
.navable-plan.json resolves to your app’s repo root when the server’s cwd is not the project.
Recommended: Agent Skills
For a deterministic, repeatable workflow, pair this MCP server with @navable/skills — pre-built agent skills that guide your AI agent through scanning, fixing, reviewing, and auditing accessibility issues step by step.
The skills ensure your agent follows a consistent process (scan → plan → fix → verify) instead of improvising. Copy them into your project's skills folder:
# VS Code (Copilot)
cp -r skills/* .github/skills/
# Cursor
cp -r skills/* .agents/skills/
# Claude Code
cp -r skills/* .claude/skills/See the skills repository for details.
Requirements
Node.js >= 20
Playwright Chromium — downloaded automatically on first scan. If auto-install fails, run
npx playwright install chromiummanually.
Contributing / development
We love getting feedback and contributions. Found a bug? Have an idea for a new fix pattern or ARIA guide? Open an issue or send a PR — we'll review it quickly.
git clone https://github.com/web-DnA/navable-web-accessibility-mcp.git
cd navable-web-accessibility-mcp
npm install
npx playwright install chromium
npm run dev # watch modeLicense
MIT — navable.io
Available Tools
3 toolsgenerate_fix_planAccessibility Fix Plan GeneratorA
Convert a scan result into a structured AccessibilityFixPlan and write it to .navable-plan.json.
PREFERRED WORKFLOW:
Call run_accessibility_scan — it returns a "scanId" field in the result.
Call generate_fix_plan with { scanId: "<value from step 1>" }. The scanId lookup is server-side — no need to pass the full scan JSON back.
FALLBACK WORKFLOW: Pass the full scan JSON as { scan: }. Use only when the scanId is no longer available (server was restarted; last 10 scans are kept).
WRITE LOCATION: Writes .navable-plan.json to the project root (auto-detected via package.json / .git walk-up). If the file ends up in the wrong place, set the NAVABLE_PROJECT_ROOT environment variable in your MCP server config to the absolute path of your project directory.
RESPONSE: Always includes "planPath" — the absolute path where the file was written. On write failure, returns an error with the attempted path and instructions to set NAVABLE_PROJECT_ROOT.
Inputs: scan, scanId, compact, writeToDisk.
run_accessibility_scanWCAG Accessibility ScannerARead-only
Scan a URL for WCAG 2.1 Level A + AA accessibility violations using Playwright + axe-core, with optional Pa11y (HTMLCS) as a second engine.
Returns structured violations grouped by severity with WCAG criteria and fix hints. Requires the target URL to be running and reachable.
ENGINES:
Default: ["axe"]. Pass {"engines": ["axe", "htmlcs"]} to also run Pa11y/HTMLCS.
Crossover findings are deduped server-side: an axe violation also flagged by HTMLCS is
marked with alsoFlaggedBy: ["htmlcs"]. Adding HTMLCS typically grows the result by
~10-20% (mostly standalone HTMLCS findings) and adds ~2-4s wall-clock per scan.
NEXT STEP: The result includes a "scanId" field. Pass it directly to generate_fix_plan: generate_fix_plan({ scanId: "" }) Do NOT pass the full scan result object - use the scanId instead.
Inputs: url (required), tags, compact, engines, +2 more.
update_fix_statusFix Status UpdaterA
Update the status of one or more items in .navable-plan.json.
Use after applying a fix to mark it as done, or to skip an item. Reads the plan from the project root (or planPath), updates the matching items, and writes the file back. Returns the updated summary.
Inputs: fixId (required), status (required), planPath.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool serves a distinct function: scanning, generating a fix plan, and updating status. No overlap.
All tool names follow a consistent verb_noun pattern with snake_case (run_accessibility_scan, generate_fix_plan, update_fix_status) and clear verbs.
Three tools is well-scoped for a specialized accessibility scanning and fix-planning domain, covering the essential actions without bloat.
Covers the core workflow: scan, generate plan, update status. Minor gaps like viewing the plan metadata or listing scans, but the set is complete for the primary use case.
Maintenance
Related MCP Connectors
Run WCAG accessibility scans on websites, list each issue with its element, and triage from chat.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Scan URLs for WCAG 2.1 violations, generate AI fixes, and produce VPAT 2.5 compliance reports.
Free WCAG 2.2/ADA/508 accessibility MCP: scan, AI fixes, verify, vision audit, localhost tunnel
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables automated web accessibility scans for WCAG compliance using Playwright and Axe-core, providing visual and JSON reports with remediation guidance.252,963 npm59MIT
- AlicenseBqualityDmaintenanceEnables AI agents to perform comprehensive accessibility audits on websites using Playwright and axe-core against WCAG standards. Provides detailed compliance reports with violation summaries and remediation guidance across multiple browsers.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to test web accessibility by scanning URLs, detecting violations, and running focused audits on keyboard navigation, screen reader compatibility, and WCAG criteria — all within the assistant's loop.MIT

axe MCP Serverofficial
FlicenseNot gradedqualityCmaintenanceEnables AI agents to scan web pages for accessibility issues and get AI-powered remediation guidance using Axe DevTools for Web.10-