Skip to main content
Glama

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

Available Tools

21 tools
check-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

    A3.6/5.0

    Scored across 21 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      11
      21 npm
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Exposes 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.
      5
      9 npm
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      8
      36 PyPI
      MIT