Accessibility Testing

Automated WCAG testing with axe MCP -- analyze, remediate, fix, and verify

Overview

What It Does

Runs Deque axe analysis via MCP, provides remediation guidance, optionally auto-fixes source code.

1. Analyze

Runs axe analyze on the URL. Produces a violation table with rule IDs, impact levels, affected elements, and WCAG criteria.

2. Remediate

Calls axe remediate for each violation to get Deque’s recommended fix — not a guess, but axe’s own guidance.

3. Fix

With —fix, locates source files (HTL, JS, SCSS) and applies fixes following axe guidance and project accessibility patterns.

4. Verify

Re-runs analysis after fixes and produces a before/after comparison table.

Setup

Prerequisites

Docker, an API key, and the dx-core plugin.

RequirementWhy
Docker runningaxe MCP Server runs as a Docker container
Axe DevTools API keyRequired by the axe MCP Server for analysis
dx-core pluginThe skill and MCP config live in this plugin

Step-by-Step Setup

1. Pull the Docker image (one-time) 
docker pull dequesystems/axe-mcp-server:latest
2. Get an API key 
# Go to https://axe.deque.com/settings
# Copy your API key
3. Export the API key (add to ~/.zshrc or ~/.bashrc) 
export AXE_API_KEY=“your-key-here”
4. Reinstall the plugin to pick up MCP config 
/plugin install dx-core@dx-aem-flow

Verify Setup

Run any /dx-axe command. If axe MCP tools load successfully, setup is complete. If you see “axe MCP Server setup” instructions, revisit the steps above.

Usage

Running Accessibility Tests

Analyze pages, auto-fix violations, and test against specific WCAG standards.

Command syntax 
/dx-axe <URL> [—fix] [—standard wcag2aa|wcag21aa|best-practice]
ArgumentRequiredDefaultDescription
<URL>Yes—Page URL to test
—fixNooffAuto-apply fixes after analysis
—standardNowcag2aaWCAG standard to test against

Examples

Analyze a page (report only) 
/dx-axe http://localhost:4502/content/mysite/en/home.html?wcmmode=disabled
Analyze and auto-fix 
/dx-axe http://localhost:4502/content/mysite/en/home.html?wcmmode=disabled —fix
Test against WCAG 2.1 AA 
/dx-axe https://qa.example.com/en/products.html —standard wcag21aa
Pages

Accessing Different Environments

Local AEM, QA/Stage with basic auth, and public URLs.

Local AEM

Embed admin credentials in the URL. The Docker container uses —add-host to reach your host machine.

/dx-axe http://admin:admin@localhost:4502/content/mysite/en/home.html?wcmmode=disabled

QA / Stage

Protected with HTTP Basic Auth. Embed credentials or configure in .ai/config.yaml under aem.qa-basic-auth.

/dx-axe https://user:pass@qa.example.com/content/mysite/en/home.html

Public URLs

No special handling needed.

/dx-axe https://www.example.com/products

Docker Networking

Inside Docker, localhost refers to the container, not your host. If localhost does not resolve, use host.docker.internal:4502 instead. The plugin’s —add-host flag enables this. Add ?wcmmode=disabled to test published rendering.

Fix

Fix Priorities

How the skill chooses what to fix and how.

Fix Strategy

  • Semantic HTML over ARIA workarounds
  • Existing SCSS mixins for focus states
  • Project design tokens for color contrast
  • Third-party/vendor code is flagged, not modified

Output Report

Saves a11y-report.md to the spec directory with:

  • URL tested and date
  • WCAG standard used
  • Full violation table
  • Remediation actions taken (if —fix)
  • Before/after verification results
Config

MCP Server Configuration

The plugin handles Docker startup automatically.

Plugin .mcp.json (auto-configured) 
{
"mcpServers": {
  "axe-mcp-server": {
    "command": "docker",
    "args": [
      "run",
      "--add-host=host.docker.internal:host-gateway",
      "-i", "--rm",
      "-e", "AXE_API_KEY",
      "dequesystems/axe-mcp-server:latest"
    ]
  }
}
}

How It Works

Docker’s -e AXE_API_KEY passes the env var from your shell into the container via normal environment inheritance — no “env” block needed in .mcp.json. The —add-host flag lets the container reach localhost services on your host machine.

Help

Troubleshooting

Common issues and fixes.

"axe MCP Server setup" message

Docker is not running, the image is not pulled, or AXE_API_KEY is not exported. Follow the setup steps and verify with docker run —rm -e AXE_API_KEY dequesystems/axe-mcp-server:latest —help.

Docker cannot reach localhost:4502

Inside Docker, localhost is the container. Use host.docker.internal:4502 instead.

QA URL returns 401

Environment requires Basic Auth. Embed credentials in the URL or configure in .ai/config.yaml under aem.qa-basic-auth.

API key error

Verify: echo $AXE_API_KEY. If empty, re-export and restart your terminal. If expired, get a new key from axe.deque.com/settings.

KAI by Dragan Filipovic