@webability/mcp

@webability/mcp

Accessibility testing MCP server for Cursor, VS Code Copilot, Claude Code, and any other MCP-compatible IDE.

What is WebAbility?

WebAbility.io is an AI-powered web accessibility platform — widget, scanner, and agents for WCAG 2.2 / ADA / Section 508 / EAA compliance. This MCP exposes the same scanning engine that powers the WebAbility widget and dashboard, so you can audit and fix accessibility issues from your IDE while you build.

The server registers an instructions block on initialize, so any MCP-compatible client picks up business context (what tool to call when, the three-tier output convention, etc.) automatically — no setup required beyond the install below.

Lite (local) vs Full (hosted)

	Lite — local stdio (npx / webability-mcp)	Full — hosted (https://mcp.webability.io/mcp)
Account	None	Free WebAbility account + token
Scan / fix / verify	Yes (on your machine)	Yes
find_source / scan_history	Yes	No
visual_audit / start_audit / get_audit	Listed as stubs → connect Full (still free)	Yes — free with your account
PostHog / dashboard analytics	Optional env only	On by default on hosted

Lite is the no-account wedge: DOM scanners and the find → fix → verify loop. Full adds vision audit and compliance reports — free with a WebAbility account (dashboard / Smithery). Lite lists those Full tools as stubs so agents know to upgrade.

Why this over other accessibility MCPs

Most accessibility MCP servers stop at find and suggest. WebAbility closes the whole loop in your editor, and starts free:

• Free Lite scan — no account, no Docker. scan_page runs entirely on your machine. (Deque's axe MCP needs a paid subscription, an API key, and a Docker install just to analyze a page.)
• Fixes that fit your stack. generate_ai_fix returns ready-to-paste code for the framework you actually use — Tailwind, MUI, Bootstrap, WordPress, Next.js — not generic guidance.
• A vision pass on Full (free with account). Hosted visual_audit catches focus visibility, icon contrast, and "looks like a button but isn't" — issues axe-core structurally cannot see.
• Verification, not just detection. verify_fix re-checks that your fix actually landed and returns verified: true/false. Every 2026 comparison of accessibility MCPs names this the biggest gap in the category — most tools never close it.
• Evidence for compliance on Full (free with account). start_audit produces a persistent, timestamped report and Excel workbook you can hand to an auditor — not a result that vanishes with your session.

The Lite cycle: scan_page → generate_ai_fix → verify_fix. On Full (free account), add start_audit when you need the paper trail.

Install

npm install -g @webability/mcp

Setup

Add to your IDE's MCP config:

{
  "mcpServers": {
    "webability": {
      "command": "webability-mcp"
    }
  }
}

Optional env:

• WEBABILITY_API_URL (default https://api.webability.io) for self-hosted backends.
• POSTHOG_PROJECT_API_KEY or POSTHOG_API_KEY to enable PostHog MCP Analytics for MCP initialize, tools/list, and tool-call usage events.
• POSTHOG_HOST (default https://us.i.posthog.com) for EU or self-hosted PostHog ingestion.
• WEBABILITY_POSTHOG_MCP_ANALYTICS=off to force-disable PostHog MCP Analytics even when a PostHog key is present.

Scan engines

scan_page runs three engines in parallel and deduplicates the results:

Engine	Rules	What it covers
WebAbility detectors	60+	Gradient-aware contrast, weak names, decorative icons, landmark hierarchy, ARIA correctness, link consistency, target size, keyboard traps
axe-core	104	Industry-standard WCAG 2.2 baseline
HTML_CodeSniffer	200+	Section 508 + WCAG techniques cross-reference

Three-tier output (since v1.2.1)

Every scan returns:

• issues — high-confidence violations, safe to surface as bugs
• incomplete — findings that need human review (contrast against gradients, marketing imagery, framer-motion pre-animation states, axe-incomplete). Never auto-fix these.
• summary — counts by severity + an incomplete count

This mirrors axe-core's violations / incomplete / passes split and prevents agents from "fixing" false positives in destructive ways.

Tools

Tool	Edition	What it does
scan_page	Lite + Full	Scan a URL for WCAG accessibility issues (3 engines)
flow_scan	Lite + Full	Multi-page journey scan with deduplicated issues across pages
scan_html	Lite + Full	Scan a raw HTML snippet (no URL needed)
detect_framework	Lite + Full	Detect Tailwind / MUI / Bootstrap / Next.js / WP / plain CSS
generate_ai_fix	Lite + Full	Framework-aware fix alternatives. Auto-extracts brand palette from the live URL on contrast issues.
verify_fix	Lite + Full	Re-scan a fixed element and confirm the violation is gone — verified: true/false. Closes the find → fix → verify loop.
check_color_contrast	Lite + Full	WCAG contrast check on a color pair; pass url to get brand-aligned suggestions from the live page
check_aria	Lite + Full	Validate ARIA attributes in an HTML snippet
get_rules	Lite + Full	List axe-core rules with optional WCAG tag filter
find_source	Lite only	Map a CSS selector back to local source files
scan_history	Lite only	Browse prior local scans under ~/.webability/scans/
visual_audit	Full (free w/ account; stub on Lite)	Pixel-level audit via vision (icon contrast, focus visibility, looks-like-a-button-but-isn't)
start_audit	Full (free w/ account; stub on Lite)	Kick off the full server-side audit deliverable (report + Excel workbook). Returns an id to poll.
get_audit	Full (free w/ account; stub on Lite)	Check an audit's progress and, once complete, get the severity summary + report/workbook download URLs.

When to use this MCP

• Building a new component and want it accessible from day one
• Auditing a localhost / staging build before pushing
• Triaging a Lighthouse / axe report — scan_page consolidates all three engines
• Generating fix suggestions that match the framework you're already using
• Checking color contrast against the user's actual brand palette (not generic suggestions)

Examples

In Cursor / Claude Code:

"Scan localhost:3000 for accessibility issues"

"Walk login → dashboard → checkout and report unique issues across the flow"

"Suggest a fix for the contrast issue on .btn-primary on https://example.com — match their brand colors"

"What does WCAG 1.4.11 check?"

Privacy, scan logs & telemetry

Every scan is logged locally to ~/.webability/scans/ — a one-line-per-scan index.jsonl ledger plus the full result of your last 500 scans. Browse them with the scan_history tool ("what did we scan earlier?") or plain jq. Set WEBABILITY_SCAN_LOG=off to disable, WEBABILITY_SCAN_LOG_DIR to relocate.

The server also reports one small telemetry event per tool call (every tool, not just scans) to the WebAbility API: tool name, a short target label (URL, selector, issue type — never page content), pass/fail, duration, issue counts, and a persistent anonymous install ID. Full scan results, HTML, and generated fix code never leave your machine via telemetry. Set WEBABILITY_SCAN_TELEMETRY=off to opt out.

If POSTHOG_PROJECT_API_KEY or POSTHOG_API_KEY is configured, the server additionally enables PostHog MCP Analytics. This captures MCP usage metadata such as initialize, tools/list, tool name, duration, client name/version, and success/failure. WebAbility strips PostHog's $mcp_parameters and $mcp_response fields before send, so raw HTML snippets, screenshots, scan responses, and generated code are not sent to PostHog by this integration.

Two tools — generate_ai_fix and visual_audit — additionally send page content (an HTML snippet or a screenshot) to WebAbility's API so it can call a third-party LLM on your behalf; WebAbility doesn't store that content, but the LLM provider sees it in transit. See PRIVACY.md for the full per-tool breakdown and WebAbility's privacy policy.

Links

• WebAbility — platform, widget, dashboard
• Documentation
• GitHub

License

MIT