home / mcp / accessibility testing mcp server

Accessibility Testing MCP Server

Runs axe-core and IBM Equal Access accessibility tests against URLs or HTML content across multiple viewports.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "joe-watkins-accessibility-testing-mcp": {
      "command": "node",
      "args": [
        "/path/to/accessibility-testing-mcp/build/index.js"
      ],
      "env": {
        "WCAG_LEVEL": "2.2_AA",
        "A11Y_ENGINE": "axe",
        "SCREEN_SIZES": "1280x1024,320x640",
        "BEST_PRACTICES": "true",
        "HEADLESS_BROWSER": "true"
      }
    }
  }
}

You can run Accessibility Testing MCP to evaluate web accessibility using two engines, Axe-core and IBM Equal Access, across multiple viewport sizes. This enables you to identify violations, gather recommendations, and verify improvements with repeatable, automated checks.

How to use

Choose your testing engine using the environment configuration to run Axe-core, IBM Equal Access, or both. You can test any URL or HTML content and get structured results for violations, recommendations, and manual checks. Run tests across multiple viewport sizes to catch responsive accessibility issues. The results clearly separate failures from passes and indicate when human review is needed.

How to install

Install the MCP server dependencies and build the project to prepare the executable that runs the accessibility tests.

npm install
npm run build

Configuration and usage notes

Configure the MCP server with environment variables to select the testing engine, WCAG level, whether to include best practices, viewport sizes, and whether to run the browser headless. The WCAG level you choose automatically configures both Axe-core tags and IBM Equal Access policies.

Details you’ll commonly adjust include:

• A11Y_ENGINE: choose axe for Axe-core, ace for IBM Equal Access, or set up to use both depending on your needs.

• WCAG_LEVEL: select a WCAG version and level, such as 2.1_AA or 2.2_AA.

• BEST_PRACTICES: enable or disable best-practices recommendations.

• SCREEN_SIZES: list viewport sizes in WIDTHxHEIGHT format to test, for example 1280x1024,320x640.

• HEADLESS_BROWSER: set to true to run in headless mode or false to see a visible browser.

The following samples show how to configure the MCP client in common environments.

VS Code (GitHub Copilot) configuration example

"mcp": {
  "servers": {
    "accessibility-testing-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/accessibility-testing-mcp/build/index.js"],
      "env": {
        "A11Y_ENGINE": "axe",
        "WCAG_LEVEL": "2.2_AA",
        "BEST_PRACTICES": "true",
        "SCREEN_SIZES": "1280x1024,320x640",
        "HEADLESS_BROWSER": "true"
      }
    }
  }
}

Claude Desktop configuration example

{
  "mcpServers": {
    "accessibility": {
      "command": "node",
      "args": ["/path/to/accessibility-testing-mcp/build/index.js"],
      "env": {
        "A11Y_ENGINE": "ace",
        "WCAG_LEVEL": "2.2_AA",
        "BEST_PRACTICES": "true"
      }
    }
  }
}

Understanding results

When you run Axe-core, you will see: Violations (definite accessibility failures), Incomplete (needs manual review), Passes (rules that passed), and Inapplicable (rules that don’t apply). IBM Equal Access provides Violations, Potential Violations, Recommendations (when BEST_PRACTICES is true), and Manual Checks (requires human testing).

WCAG_LEVEL values

Choose from the following levels to control which rules are applied during tests. The level you select affects both engines.

- 2.0_A: WCAG 2.0 Level A - 2.0_AA: WCAG 2.0 Level AA - 2.1_A: WCAG 2.1 Level A - 2.1_AA: WCAG 2.1 Level AA (default) - 2.1_AAA: WCAG 2.1 Level AAA - 2.2_A: WCAG 2.2 Level A - 2.2_AA: WCAG 2.2 Level AA - 2.2_AAA: WCAG 2.2 Level AAA

Dependencies

The MCP server relies on the following components to run the accessibility tests: @modelcontextprotocol/sdk, axe-core, accessibility-checker, and playwright for headless browser automation.

Notes

Environments shown here use placeholder paths for the runtime index file. Replace /path/to/accessibility-testing-mcp/build/index.js with the actual build output location in your setup. Ensure you have Node.js installed and that you have run the build step before starting the MCP runtime.

Tools you can use with this MCP server

The MCP server exposes the following testing tools to interact with accessibility checks. You can choose a single engine or run both for comprehensive coverage.

Available tools

analyze_url

Test any URL for accessibility issues using the selected engine(s) and report violations, incomplete items, and passes.

analyze_url_json

Test a URL and return the raw JSON output for programmatic processing.

analyze_html

Test HTML content directly for accessibility issues.

analyze_html_json

Test HTML content and return the raw JSON output.

get_rules

List all available accessibility rules that can be checked by the engines.