Claude Code Plugin

Overview

The axe Accessibility plugin is Deque's accessibility toolkit for coding agents, installed and run from Claude Code. Installing it does three things at once:

• Registers the server. The plugin ships a ready-made MCP server entry, so you don't hand-write a .mcp.json.
• Teaches Claude how to use the tools. A background skill loads automatically on accessibility work, so Claude follows the analyze → remediate → verify loop, batches remediate correctly, and maps fields between the tools without guessing.
• Adds three slash commands for setup, generating repo-level agent instructions, and running the full remediation loop on a page.

The plugin is open source at github.com/dequelabs/axe-accessibility and is licensed MIT.

It isn't only for Claude Code

Claude Code is where the plugin runs, but two of its commands produce output for other agents and editors:

• /axe-accessibility:mcp-generate-instructions writes the analyze → remediate → verify workflow into .github/copilot-instructions.md, Cursor rules, or AGENTS.md as readily as into CLAUDE.md. Anyone on the team using Copilot or Cursor inherits the workflow from the repository, whether or not they have the plugin — or Claude Code — installed.
• /axe-accessibility:mcp-setup can configure the axe MCP Server for Cursor, VS Code with Copilot, or Claude Desktop, not just Claude Code.

So it's reasonable to install the plugin purely as a setup and instruction-authoring tool for a repository whose contributors use a mix of agents.

Requirements

To install the plugin:

• Claude Code with plugin support.

To run scans — that is, to use the analyze, igt, and remediate tools, whether from Claude Code or from another client the plugin configured:

• An axe DevTools for Web subscription that includes axe MCP Server access. Without it, the tools will fail to authenticate.
• One runtime, depending on which distribution you use:
  • npm (what the plugin ships): Node.js 22.19.0 or later, plus a one-time Chromium install. See Install Chromium — the server does not download a browser for you, and skipping this step is the most common first-run failure.
  • Docker: Docker installed and running. Chromium ships inside the image.
• For OAuth 2.0 authentication: an active Node.js LTS release, since the configuration calls npx @deque/axe-auth.

Only the first applies if you're installing the plugin solely to run /axe-accessibility:mcp-generate-instructions — writing agent-instruction files needs neither a runtime nor a subscription.

Installation

Add Deque's marketplace and install the plugin from within Claude Code:

/plugin marketplace add dequelabs/axe-accessibility
/plugin install axe-accessibility

The first command registers the dequelabs/axe-accessibility repository as a plugin marketplace (the repository doubles as its own marketplace). The second installs the plugin from it. You only need to add the marketplace once — later installs and updates can skip that step.

Restart Claude Code when prompted so the MCP server loads.

Authentication

The plugin's bundled server configuration is auth-agnostic: at startup it tries to mint an OAuth access token, and makes sure exactly one credential reaches the server — the OAuth token if you're logged in, otherwise your AXE_API_KEY.

Pick whichever method suits you:

• API key — create one in the axe Account Portal under API Keys → ADD NEW API KEY, choosing the axe MCP Server product. Then export it in your shell so Claude Code can read it:

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

  Add the line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it. Never commit the key to a file in your repository.

• OAuth 2.0 — log in once with the @deque/axe-auth CLI:

  npx -y @deque/axe-auth login

  This opens a browser for the PKCE flow and stores tokens in your OS keychain, refreshing them automatically. See Authentication for the full flow, session management, and platform support.

The bundled configuration handles this rule for you, and it has to work harder than a Docker configuration would. A container only receives the variables passed with explicit -e flags, but the npm distribution inherits your entire shell environment — so an exported AXE_API_KEY and an active OAuth session would otherwise both reach the server and stop it from starting. The bundled entry clears any inherited AXE_ACCESS_TOKEN first, then, if it can mint a fresh token, unsets AXE_API_KEY before setting it. OAuth wins when both are available.

Private cloud and on-premises deployments

The npm distribution inherits AXE_SERVER_URL from your shell, so exporting it alongside your credential is enough:

export AXE_SERVER_URL="https://your-axe-instance.example.com"

If you use OAuth, also pass the same URL when logging in: npx -y @deque/axe-auth login --server https://your-axe-instance.example.com. If AXE_SERVER_URL is unset, the server defaults to https://axe.deque.com (Deque's shared US SaaS instance). See Configuration Reference.

Verifying the installation

1. Restart Claude Code.

2. Run /mcp and confirm axe-mcp-server is listed and connected, with the analyze, igt, and remediate tools available.

3. Run a smoke scan against a known page:

   Analyze https://dequeuniversity.com/demo/mars for accessibility issues

A successful scan of a real page returns a sizable payload — tens of kilobytes is normal, not an error. If your client complains the result is too large, scope the scan with analyze's selector parameter.

If the server doesn't connect, confirm your Node version, that Chromium is installed, and that exactly one credential is set, then see Troubleshooting.

What's included

The mcp-usage skill

You never invoke this one directly. It loads automatically whenever a task involves accessibility, a11y, WCAG conformance, or fixing accessibility issues in web UI, and it gives Claude the operating knowledge that otherwise has to be hand-written into a CLAUDE.md:

• The workflow. Analyze the page, remediate the violations, then re-analyze to verify zero violations before calling the work done.
• Field mapping. How each issue from analyze maps onto remediate's parameters — the most common source of error when an agent wires the two tools together by guesswork. It includes the traps: issues arrive under the response's data array, and an issue's own remediation field is an object of raw check data, not the string the remediate parameter wants.
• Batching. remediate takes an issues array of 1–25 per call, each with a caller-invented id. One call per scan, not one per issue — a per-issue call shape is rejected outright.
• Credit awareness. Credits are consumed per issue, not per call, so batching is the contract rather than a discount. Re-running analyze to verify consumes none, so verification is cheap.
• Which findings to trust. Issues flagged isAdvanced: true come from Advanced Rules — AI and computer vision — and are probabilistic, so they warrant confirmation against the real UI. Standard axe-core findings (isAdvanced: false) are deterministic and authoritative.
• Keyboard testing. When to reach for igt, and how its issue shape differs from analyze's.
• Rule-specific nuance. Guidance for judgment-heavy rules such as image-alt, color-contrast, link-name/button-name, and form labeling.

Because the skill is always available, plain-language requests work without ceremony:

Make the checkout page at http://localhost:3000/checkout accessible

Commands

/axe-accessibility:mcp-setup

/axe-accessibility:mcp-setup [client]

Walks you through connecting the axe MCP Server, asking about the decisions rather than assuming them. Optionally pass a client — claude-code, cursor, vscode, or claude-desktop — to skip that question.

The command:

1. Asks whether you want the npm or Docker distribution, then verifies that runtime — Node version and Chromium for npm, a running daemon for Docker.
2. Asks whether you want API key or OAuth 2.0 authentication, then walks through creating a key in the Account Portal or running the browser login.
3. Writes the matching configuration for your client — merging into any existing MCP configuration rather than overwriting it. For Claude Code on the npm distribution, the plugin's bundled server usually makes this step unnecessary.
4. Offers the optional settings worth knowing about: AXE_SERVER_URL for private cloud, AXE_ADVANCED_RULES for a standing Advanced Rules default, and AXE_CHROME_PATH to reuse a browser you already have (npm only).
5. Verifies the connection and runs a smoke scan.

Useful even though installing the plugin already registers the server: run it when you need to set up authentication for the first time, switch to Docker, point at a private cloud instance, or configure a different editor on the same machine. The client snippets it emits are the same ones documented for VS Code with Copilot, Cursor, and Claude Code — the command just picks the right one and merges it into your existing configuration for you.

/axe-accessibility:mcp-generate-instructions

/axe-accessibility:mcp-generate-instructions [targets]

Writes the mandatory analyze → remediate → verify workflow into your repository's agent-instruction files, so any coding agent working in the repo — not just the one that has the plugin installed — follows it. Targets:

With no argument, the command detects which of these files already exist and confirms the set with you before writing.

Each file gets the full contract, not just the loop: the remediate batching rule, the field mapping, the deterministic-versus-advanced trust distinction, the igt keyboard section, and the credit note. Tool names are adapted per target, since clients namespace MCP tools differently — Copilot binds to mcp_axe-mcp-server_analyze, for example, while Claude Code and Cursor resolve plain names.

Existing files are merged, not clobbered: if an accessibility workflow section is already present it's updated in place, otherwise the section is appended and the rest of the file is preserved. The command also tailors the instructions to your repository where it can — for example, referencing your project's real dev-server URL and start command instead of a placeholder.

/axe-accessibility:mcp-generate-instructions all

Generating all is the usual choice for a shared repository: one person runs it once from Claude Code, commits the files, and every contributor's agent picks up the workflow — Copilot from .github/copilot-instructions.md, Cursor from .cursor/rules/accessibility.mdc, and so on. The instructions only take effect for agents that read them, and each contributor still needs the axe MCP Server connected in their own client for the workflow to actually run.

This is the automated equivalent of the template in Configuring Your AI Agent.

/axe-accessibility:mcp-audit

/axe-accessibility:mcp-audit <url> [max-rounds]

Runs the full remediation loop on a page and applies the fixes to your source code. Pass the complete URL including scheme and port. If you omit it, the command tries to detect a running dev server from your package.json scripts and common ports, and confirms the URL with you before scanning.

Each round:

1. Analyze the URL and collect the issues.
2. Triage them by flag — isAdvanced findings get confirmed against the real UI before anything is changed, isNeedsReview findings are surfaced to you rather than auto-fixed when the call is a design decision, and isBestPractice findings never block "clean".
3. Remediate every issue from the round in a single batched call (up to 25 per call, split into sequential batches beyond that).
4. Apply the guidance to your source code, correlating each result back by id and checking its status, since a batch can partially fail. Suggested code fixes are adapted to the real component rather than pasted verbatim.
5. Re-analyze to verify.

The loop stops at zero violations or after max-rounds (default 5). It also stops early if a round makes no progress — at that point the remaining issues typically need a design decision, or are advanced-rule false positives, which the command reports as such rather than contorting your code to reach zero. Progress is reported per round (for example, round 1: 7 → round 2: 2 → round 3: 0), and the command summarizes the code changes it made so you can review them before committing.

/axe-accessibility:mcp-audit http://localhost:3000/checkout 3

Reaching a page that isn't a plain URL works the way it does for the underlying tool: describe a login or interaction and the steps are passed through as before actions; describe environment routing or a pre-authenticated session and they're passed as cookies, which apply before navigation. Keep secrets in a fill step's value or a cookie's value, never in a selector or a cookie name.

Once automated violations are clean, the command can run an optional keyboard pass with igt — focus order, focus traps, and focus visibility are invisible to a static scan. Ask for it directly if you want it on a page with menus, dialogs, or custom widgets:

/axe-accessibility:mcp-audit http://localhost:3000 and run the keyboard test

Suggested workflow

1. /axe-accessibility:mcp-setup — connect and authenticate the server. Verify with /mcp.
2. /axe-accessibility:mcp-generate-instructions all — bake the workflow into the repository so every agent and teammate inherits it.
3. /axe-accessibility:mcp-audit http://localhost:3000 — clean up the accessibility debt already on the page.
4. From then on, just build. The mcp-usage skill keeps Claude running the loop on UI changes without being asked.

Managing the plugin

Claude Code's /plugin command manages the plugin's lifecycle:

/plugin                 # browse and manage installed plugins
/plugin update axe-accessibility
/plugin uninstall axe-accessibility

Uninstalling removes the bundled MCP server entry along with the skills and commands. Any agent-instruction files written by /axe-accessibility:mcp-generate-instructions stay in your repository — remove them yourself if you no longer want them.

Related pages

• Choosing a Distribution — npm versus Docker, and installing Chromium for npm
• Setup in Claude Code — configuring the server by hand, without the plugin
• Authentication — API key and OAuth 2.0 in full
• Configuration Reference — environment variables and agent instruction templates
• Advanced Rules — presets, precedence, and what the isAdvanced flag means
• Troubleshooting — connection, Chromium, Docker, and authentication errors
• AI Credits — how remediate and igt consume credits