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:

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

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 parse if modifying the parser
Submit a pull request

License

MIT

Resources