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