Setup in Claude Code

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

Axe MCP server can be added at either the project or user level.

Choose scope

  • Project-level: Create a file at .mcp.json in your project's root directory (best for sharing settings with a team)
  • User-level: Create or edit the configuration file at:
    • macOS/Linux: ~/.config/claude-code/mcp.json
    • Windows: %APPDATA%\claude-code\mcp.json

Adding configuration JSON

Add the following configuration JSON.

info

If you already have other servers defined, add the axe-mcp-server block inside the existing mcpServers object.

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--add-host=host.docker.internal:host-gateway",
        "-i",
        "--rm",
        "-e", "AXE_SERVER_URL",
        "-e", "AXE_API_KEY",
        "dequesystems/axe-mcp-server:latest"
      ],
      "env": {
        "AXE_SERVER_URL": "https://axe.deque.com",
        "AXE_API_KEY": "${AXE_API_KEY}"
      }
    }
  }
}
note

The configuration uses "AXE_API_KEY": "${AXE_API_KEY}" for secure input handling. The ${AXE_API_KEY} syntax instructs Claude Code to pull the value from your shell environment. For more information, see the Claude Code MCP documentation.

note

Using a regional, private cloud, or on-premises axe instance? Update the AXE_SERVER_URL value in the env block with your instance's base URL:

"env": {
  "AXE_API_KEY": "${AXE_API_KEY}",
  "AXE_SERVER_URL": "https://your-axe-instance.example.com"
}

If omitted, the server defaults to https://axe.deque.com (Deque's shared US SaaS instance). See Configuration Options for details.

Set your API key

Set your API key as an environment variable in your shell:

export AXE_API_KEY="your-api-key-here"

For permanent setup, add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Usage and verification

Once configured, restart Claude Code to load the MCP server.

  1. Launch Claude Code from your terminal: claude
  2. Type /mcp to manage MCP server connections
  3. You should see axe-mcp-server listed with the analyze and remediate tools available

To ensure Claude Code uses the axe MCP Server tools correctly, add the following instructions to a CLAUDE.md file in your project root. This tells Claude to follow the proper analyze-then-remediate workflow.

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- First use `remediate` tool for EACH violation found
- Provide the exact HTML element, rule ID, and issue description
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 3. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

For more details on agent instructions, see Configuring Your AI Agent.

Is this page helpful?

Help us improve this page

Still need help?