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.

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-role | Get detailed information about a specific ARIA role | | list-roles | List all ARIA roles, optionally filtered by category | | search-roles | Search for roles by keyword in name or description | | get-role-hierarchy | Get the inheritance hierarchy for a role | | States & Properties | | | get-attribute | Get details about an ARIA state or property | | list-states | List all ARIA states with descriptions | | list-properties | List all ARIA properties, optionally global only | | get-global-attributes | List all global ARIA states and properties | | Validation | | | validate-role-attributes | Validate if attributes are allowed for a role | | get-required-attributes | Get required attributes for a role | | get-prohibited-attributes | Get prohibited attributes for a role | | Role Relationships | | | get-required-context | Get required parent context for a role | | get-required-owned | Get required child elements for a role | | Accessible Name | | | check-name-requirements | Check accessible name requirements for a role | | get-roles-requiring-name | List all roles that require an accessible name | | Specialized Queries | | | list-landmarks | List all ARIA landmark roles with usage guidance | | list-widget-roles | List interactive widget roles | | list-live-regions | List live region roles with politeness levels | | Guidance | | | suggest-role | Get role suggestions based on UI component description | | get-aria-version | Get ARIA specification version and statistics | | get-server-info | Get information about this MCP server |

Installation

npm install

Configure 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 button

Returns 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-landmarks

Lists 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-submodule

This will:

1. Pull the latest changes from the W3C ARIA repository
2. Re-parse the specification to regenerate data/aria-data.json

Manual Parsing

To regenerate the data without updating the submodule:

npm run parse

Project 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 configuration

Deployment to Netlify

This project is configured for Netlify deployment.

Deploy via GitHub

1. Push this repository to GitHub
2. Connect to Netlify via the dashboard
3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run parse if modifying the parser
5. Submit a pull request

License

MIT

Resources

• WAI-ARIA Specification
• ARIA Authoring Practices
• Model Context Protocol