Real-time accessibility and screen reader analysis for AI coding assistants.
Speakable is a local-first accessibility analysis engine and MCP server that helps AI coding assistants predict screen reader output, audit accessibility issues, and detect regressions across NVDA, JAWS, and VoiceOver — directly inside modern development workflows. Learn more at getspeakable.dev
Speakable is a well-structured, legitimate accessibility analysis tool with proper architecture and no malicious patterns. The MCP server implementation is clean with appropriate permissions scoped to file I/O and local processing. Minor code quality considerations around error handling and input validation do not materially impact security. Supply chain analysis found 4 known vulnerabilities in dependencies (2 critical, 1 high severity). Package verification found 1 issue.
5 files analyzed · 9 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"speakable-mcp": {
"args": [
"-y",
"@reticular/speakable"
],
"command": "npx"
}
}
}Once installed, try these example prompts and explore these capabilities:
From the project's GitHub README.
Simulate how NVDA, JAWS, and VoiceOver interpret your HTML — from a single CLI tool. Catch screen reader issues early, detect regressions in CI/CD, and reduce manual testing overhead.
Try it in your browser — no install needed: getspeakable.dev/tool
Speakable bridges the gap between rule-based linting tools (like axe) and manual screen reader testing. It gives you scalable, automated insight into how assistive technologies will interpret your UI.
Screen reader output is heuristic and may differ from actual behavior. Speakable complements manual testing — it doesn't replace it.
npm install @reticular/speakable
Or install globally for CLI usage:
npm install -g @reticular/speakable
# Analyze an HTML file (JSON output)
speakable page.html
# Get screen reader announcement text
speakable page.html -f text -s nvda
# Generate an accessibility audit report
speakable page.html -f audit
# Compare two versions for regressions
speakable new.html --diff old.html
# Pipe from stdin
cat page.html | speakable -
For quick one-off checks, you can also paste HTML directly into the web analyzer — same engine, no setup.
If you want to test HTML quickly without installing anything, paste it directly into the web analyzer at getspeakable.dev/tool. It runs the same simulation engine in the browser — supports NVDA, JAWS, and VoiceOver output, CSS selector filtering, and diff mode. Useful for quick iteration, debugging a specific component, or sharing results with teammates who don't have the CLI installed.
Usage: speakable [options] [input...]
Analyze HTML accessibility announcements and generate screen reader output
Arguments:
input HTML file path(s) or "-" for stdin
Options:
-v, --version Output the current version
-o, --output <path> Output file path (default: stdout)
-f, --format <format> Output format (default: "json")
-s, --screen-reader <reader> Screen reader to simulate (default: "nvda")
--selector <selector> CSS selector to filter elements
--validate Validate round-trip serialization
--diff <file> Compare with another HTML file
--batch Process multiple files in batch mode
-h, --help Display help for command
| Format | Flag | Description |
|---|---|---|
| JSON | -f json | Canonical accessibility model as JSON. Best for CI/CD and programmatic use. |
| Text | -f text | Screen reader announcement text. Human-readable output showing what each reader would say. |
| Audit | -f audit | Developer-friendly audit report with landmark structure, heading hierarchy, interactive elements, and issue detection. |
| Both | -f both | JSON and text output combined. |
| Reader | Flag | Platform |
|---|---|---|
| NVDA | -s nvda | Windows |
| JAWS | -s jaws | Windows |
| VoiceOver | -s voiceover | macOS |
| All | -s all | All three readers side by side |
Each renderer produces heuristic output approximating the real screen reader's behavior. Key differences are preserved — for example, NVDA says "navigation landmark" while JAWS says "navigation region" and VoiceOver says "navigation".
Compare two HTML files and see exactly what changed in the accessibility tree:
speakable new-version.html --diff old-version.html
speakable new-version.html --diff old-version.html -f text
The diff identifies added, removed, and changed nodes with specific property-level details (name changes, role changes, state changes, focus changes).
Focus analysis on specific elements:
# Analyze only buttons
speakable page.html --selector "button"
# Analyze a specific component
speakable page.html --selector ".my-component"
# Analyze all interactive elements
speakable page.html --selector "button, a, input, select"
Analyze multiple files in a single run:
speakable --batch file1.html file2.html file3.html
Batch mode continues processing even if individual files fail, and reports a summary at the end.
Generate comprehensive accessibility reports:
speakable page.html -f audit
The audit report includes:
When outputting to a terminal, Speakable automatically colorizes human-readable formats:
Colors are automatically disabled when piping to files or other commands.
Verify that the accessibility model serializes and deserializes consistently:
speakable page.html --validate
Speakable includes a Model Context Protocol (MCP) server that lets AI coding assistants analyze accessibility in real-time. Ask your assistant "check if this component is accessible" and it calls Speakable automatically.
Add to your MCP config (Kiro, VS Code, Cursor, Claude Desktop, Windsurf):
{
"mcpServers": {
"speakable": {
"command": "npx",
"args": ["-y", "@reticular/speakable-mcp"]
}
}
}
| Tool | Description |
|---|---|
analyze_html | Predict screen reader output for NVDA, JAWS, and VoiceOver |
audit_html | Generate accessibility audit report with issues and remediation |
diff_html | Compare two HTML versions for accessibility regressions |
All tools run locally — no network requests, no data leaves your machine. See the MCP Integration docs for full setup instructions.
- name: Run Speakable
run: npx @reticular/speakable page.html -f audit
- name: Check for regressions
run: npx @reticular/speakable new.html --diff baseline.html -f text
| Code | Meaning |
|---|---|
| 0 | Success — analysis completed, no issues |
| 1 | User error — invalid arguments or options |
| 2 | Content error — accessibility issues found, or diff detected changes |
| 3 | System error — file not found, I/O failure |
Use exit codes in CI to fail builds on regressions:
speakable new.html --diff baseline.html || echo "Accessibility regression detected"
Speakable can also be used as a library:
import {
parseHTML,
buildAccessibilityTree,
serializeModel,
renderNVDA,
renderJAWS,
renderVoiceOver,
renderAuditReport,
diffAccessibilityTrees,
} from '@reticular/speakable';
const html = '<button aria-label="Submit">Pay</button>';
const doc = parseHTML(html);
const result = buildAccessibilityTree(doc.document.body);
// Screen reader output
console.log(renderNVDA(result.model)); // "Submit, button"
console.log(renderJAWS(result.model)); // "Submit, button"
console.log(renderVoiceOver(result.model)); // "button, Submit"
// JSON model
console.log(serializeModel(result.model));
// Audit report
console.log(renderAuditReport(result.model));
Speakable processes HTML through a four-stage pipeline:
AnnouncementModel suitable for snapshot testing and diffingUse Speakable to catch issues early and reduce the manual testing burden — then validate critical flows with real screen readers.
--selector to analyze specific components rather than entire pages-s all to see cross-platform differences-f audit for a quick overview of accessibility healthMIT
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.