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: Add the server to the mcpServers object in ~/.claude.json in your home directory (applies across all of your projects). You can also manage user-level servers with the claude mcp add --scope user command — see the Claude Code MCP documentation for details.

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

Using OAuth 2.0 authentication

If you prefer OAuth over an API key, replace the configuration above with the following. This uses @deque/axe-auth token to obtain a fresh access token each time the server starts.

Before configuring, complete Step 1: Authenticate in the OAuth 2.0 Authentication guide.

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "docker run --add-host=host.docker.internal:host-gateway -i --rm -e \"AXE_ACCESS_TOKEN=$(npx -y @deque/axe-auth token)\" dequesystems/axe-mcp-server:latest"
      ]
    }
  }
}
note

Using a regional, private cloud, or on-premises axe instance? Add AXE_SERVER_URL to the Docker command and an env block with your instance's base URL:

"args": [
  "-c",
  "docker run --add-host=host.docker.internal:host-gateway -i --rm -e AXE_SERVER_URL -e \"AXE_ACCESS_TOKEN=$(npx -y @deque/axe-auth token)\" dequesystems/axe-mcp-server:latest"
],
"env": {
  "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.

note

This configuration uses sh -c to allow shell substitution. $(npx -y @deque/axe-auth token) runs at server startup and injects a valid access token into the Docker container. The -y flag skips the first-run "Ok to proceed?" prompt that npx would otherwise ask in a non-interactive shell. Do not set AXE_API_KEY alongside AXE_ACCESS_TOKEN.

caution

Windows users: This configuration uses a POSIX shell (sh) and command substitution ($(...)), which is not available in cmd.exe or PowerShell by default. Run Claude Code from a Git Bash or WSL shell so that sh is on your PATH.

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?