aria-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aria-mcp Suggest the best ARIA role for a custom searchable dropdown"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
aria-mcp
A Model Context Protocol (MCP) server providing comprehensive access to the W3C WAI-ARIA specification. Designed for accessibility professionals, developers, and AI agents to query ARIA roles, states, properties, and accessibility requirements.
Quick Start
Add to your MCP client configuration:
{
"mcpServers": {
"aria": {
"command": "npx",
"args": ["-y", "aria-mcp"]
}
}
}That's it! No cloning, no building - just add the config and start querying ARIA.
Related MCP server: accessibility-mcp
Features
Complete ARIA 1.3 Specification Data: Roles, states, properties, and their relationships
Role Validation: Check attribute validity for specific roles
Accessibility Guidance: Name requirements, landmarks, live regions
Smart Suggestions: Get role recommendations based on UI component descriptions
Works Locally & Remotely: stdio transport for local use, Netlify Functions for remote deployment
Available Tools
Tool | Description |
Role Information | |
| Get detailed information about a specific ARIA role |
| List all ARIA roles, optionally filtered by category |
| Search for roles by keyword in name or description |
| Get the inheritance hierarchy for a role |
States & Properties | |
| Get details about an ARIA state or property |
| List all ARIA states with descriptions |
| List all ARIA properties, optionally global only |
| List all global ARIA states and properties |
Validation | |
| Validate if attributes are allowed for a role |
| Get required attributes for a role |
| Get prohibited attributes for a role |
Role Relationships | |
| Get required parent context for a role |
| Get required child elements for a role |
Accessible Name | |
| Check accessible name requirements for a role |
| List all roles that require an accessible name |
Specialized Queries | |
| List all ARIA landmark roles with usage guidance |
| List interactive widget roles |
| List live region roles with politeness levels |
Guidance | |
| Get role suggestions based on UI component description |
| Get ARIA specification version and statistics |
| Get information about this MCP server |
Installation
npm installConfigure Claude Desktop
Add this to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"aria-mcp": {
"command": "node",
"args": ["/path/to/aria-mcp/src/index.js"]
}
}
}Configure Cursor
Add to your Cursor MCP settings:
{
"mcpServers": {
"aria-mcp": {
"command": "node",
"args": ["/path/to/aria-mcp/src/index.js"]
}
}
}Usage Examples
Query a Role
get-role buttonReturns complete information about the button role including:
Description and purpose
Category (widget, landmark, etc.)
Required/supported/prohibited attributes
Name requirements
Parent/child role requirements
Validate Attributes
validate-role-attributes role=button attributes=["aria-pressed","aria-expanded","aria-label"]Checks if each attribute is valid, required, or prohibited for the role.
Get Role Suggestions
suggest-role "dropdown menu with autocomplete"Returns suggested roles (combobox, listbox) with usage guidance.
List Landmarks
list-landmarksLists all ARIA landmark roles with best practices for page structure.
Data Source
This MCP server uses data parsed directly from the W3C ARIA repository, which is included as a Git submodule.
Updating the Data
To update to the latest ARIA specification:
npm run update-submoduleThis will:
Pull the latest changes from the W3C ARIA repository
Re-parse the specification to regenerate
data/aria-data.json
Manual Parsing
To regenerate the data without updating the submodule:
npm run parseProject Structure
aria-mcp/
├── src/
│ ├── index.js # MCP server with stdio transport
│ └── tools.js # Tool definitions and handlers
├── scripts/
│ └── parse-aria-spec.js # Parser for W3C ARIA HTML specs
├── data/
│ ├── aria/ # W3C ARIA repo (Git submodule)
│ └── aria-data.json # Parsed specification data
├── netlify/
│ └── functions/
│ └── api.js # Netlify Function for remote use
└── netlify.toml # Netlify configurationDeployment to Netlify
This project is configured for Netlify deployment.
Deploy via GitHub
Push this repository to GitHub
Connect to Netlify via the dashboard
Netlify will automatically build and deploy
Using the Remote Server
Once deployed, configure your MCP client:
{
"mcpServers": {
"aria-mcp": {
"command": "npx",
"args": ["mcp-remote@next", "https://your-site.netlify.app/mcp"]
}
}
}Use Cases
For Accessibility Professionals
Quick Reference: Look up role requirements without leaving your IDE
Validation: Verify ARIA usage in code reviews
Training: Help team members understand ARIA semantics
For Developers
Real-time Guidance: Get role suggestions while building components
Attribute Validation: Catch invalid ARIA usage early
Documentation: Access spec details without browser context switching
For AI Agents
Code Generation: Generate accessible components with correct ARIA
Code Review: Validate ARIA usage in pull requests
Accessibility Audits: Check for missing or incorrect attributes
ARIA Specification Coverage
100 Roles: All roles from WAI-ARIA 1.3
10 States: Dynamic values that change with user interaction
43 Properties: Static or rarely-changing characteristics
Role Categories: widget, composite, document, landmark, liveRegion, window, abstract
Contributing
Fork the repository
Create a feature branch
Make your changes
Run
npm run parseif modifying the parserSubmit a pull request
License
MIT
Resources
Available Tools
21 toolscheck-name-requirementsC
Check if a role requires an accessible name and how it can be provided.
Inputs: role (required).
get-aria-versionB
Get information about the ARIA specification version and metadata.
Inputs: no named parameters.
get-attributeB
Get detailed information about an ARIA state or property (e.g., aria-label, aria-expanded, aria-hidden).
Inputs: attribute (required).
get-global-attributesB
List all global ARIA states and properties that apply to any element.
Inputs: no named parameters.
get-prohibited-attributesC
Get all prohibited ARIA attributes for a specific role.
Inputs: role (required).
get-required-attributesC
Get all required ARIA attributes for a specific role.
Inputs: role (required).
get-required-contextC
Get the required parent context for a role (e.g., listitem requires list or group).
Inputs: role (required).
get-required-ownedB
Get the required child elements for a role (e.g., list requires listitem).
Inputs: role (required).
get-roleA
Get detailed information about a specific ARIA role including its description, properties, states, required context, and accessibility requirements.
Inputs: role (required), verbose.
get-role-hierarchyB
Get the inheritance hierarchy for a role, showing parent and child roles.
Inputs: role (required).
get-roles-requiring-nameB
List all roles that require an accessible name.
Inputs: no named parameters.
get-server-infoB
Returns information about this MCP server.
Inputs: no named parameters.
list-landmarksB
List all ARIA landmark roles with guidance on their proper usage.
Inputs: no named parameters.
list-live-regionsA
List all ARIA live region roles and explain their politeness levels.
Inputs: no named parameters.
list-propertiesB
List all ARIA properties. Optionally filter to show only global properties.
Inputs: global.
list-rolesB
List all ARIA roles, optionally filtered by category. Categories: widget, composite, document, landmark, liveRegion, window, abstract.
Inputs: category.
list-statesB
List all ARIA states with their descriptions.
Inputs: no named parameters.
list-widget-rolesC
List all interactive widget roles that represent user interface controls.
Inputs: type.
search-rolesA
Search for ARIA roles by keyword in their name or description.
Inputs: query (required).
suggest-roleB
Suggest appropriate ARIA roles based on a description of the UI component.
Inputs: description (required).
validate-role-attributesA
Validate which ARIA attributes are allowed, required, or prohibited for a specific role.
Inputs: role (required), attributes (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Every tool has a clearly distinct purpose focused on specific aspects of ARIA (roles, attributes, validation, etc.). There is no overlap in functionality, with tools like get-role, get-attribute, and validate-role-attributes each serving unique but complementary purposes. The descriptions further clarify boundaries, making misselection unlikely.
Tool names follow a consistent verb_noun pattern throughout, using hyphens as separators (e.g., get-role, list-roles, validate-role-attributes). The verbs are predictable (get, list, check, search, suggest), and the nouns clearly indicate the target resource (role, attribute, landmarks). There are no deviations in naming conventions.
With 21 tools, the count is slightly high but reasonable for the comprehensive scope of ARIA accessibility, covering roles, attributes, validation, and guidance. Each tool earns its place by addressing specific queries, though some consolidation might be possible (e.g., multiple list-* tools). It supports thorough exploration without being overwhelming.
The toolset provides complete coverage of the ARIA domain, including CRUD-like operations (get, list, validate), hierarchical relationships (get-role-hierarchy), requirements (required attributes, context), and practical utilities (suggest-role, check-name-requirements). There are no obvious gaps; agents can handle all common ARIA-related tasks without dead ends.
Related MCP Connectors
Curated knowledge API for AI agents - skill packs, semantic search, validated patterns.
Accessibility compliance for AI coding tools. WCAG 2.2 reviews with shared evidence.
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
Scan URLs or HTML for WCAG 2.2 violations. 75-rule manifest, weighted score, shareable reports.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides AI assistants with tools to grade, generate, and validate UI components against the components.build specification. Supports searching documentation, checking compliance, and generating framework-agnostic accessible components.1121 npmApache 2.0
- AlicenseAqualityDmaintenanceExposes WAI-ARIA Authoring Practices Guide (APG) patterns, providing narratives, keyboard guidance, and official source code examples for accessible widgets. It includes tools for listing patterns, retrieving specific specs, and performing semantic searches via Ollama.59 npmISC
- AlicenseAqualityDmaintenanceProvides conversational, actionable accessibility testing for AI agents, including auditing, prioritization, and code-level fixes.2214 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to perform comprehensive web accessibility checks (WCAG 2.1/2.2) including color contrast analysis, ARIA validation, and full accessibility report generation without requiring any API key.836 PyPIMIT