Mcp setup
This skill should be used when the user asks to "set up Axe MCP", "configure the Axe MCP Server", "install axe accessibility tooling", "connect Axe MCP", "authenticate axe", or runs /axe-accessibility:mcp-setup. It interactively wires the Axe MCP Server into the user's IDE/MCP client, helps choose a distribution (npm or Docker) and authentication (API key or OAuth), and verifies the connection.From its SKILL.md
npx -y skills add dequelabs/axe-accessibility --skill mcp-setupAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.2 KB, as published. Nobody here has run it
Set up the Axe MCP Server
Guide the user from nothing to a working, authenticated Axe MCP Server connection. There are two independent choices — distribution (npm or Docker) and authentication (API key or OAuth) — giving four valid configurations. Drive both with AskUserQuestion, then write the correct configuration for their client and verify it.
The one universal prerequisite is an Axe DevTools for Web subscription whose Bundle plan includes Axe MCP Server access (pricing: https://www.deque.com/axe/devtools/pricing/). Without it the tools will fail to authenticate — point the user to the pricing page. If $1 names a client, skip the client question.
Step 1 — Choose a distribution
Ask which to use (AskUserQuestion). Recommend npm for local development — it is the default the plugin ships.
- npm (recommended) — runs as a local Node process via
npx -y axe-mcp-server. Requires Node.js >= 22.19.0 and a one-time Chromium install with Playwright pinned to the server's version (below). Reacheslocalhostdev servers directly, with none of the container networking workarounds Docker needs. Auto-updates on each start. - Docker — runs as a container from
dequesystems/axe-mcp-server:latest. Requires Docker installed and running. Better when the user wants isolation, has no Node toolchain, or is standardizing CI images. Needs--add-hostplumbing to reach the host's dev server, and re-pulling to pick up new versions.
Verify the chosen prerequisite before writing config:
-
npm:
node --version(must be >= 22.19.0), then install the browser. The server does not download it for you, and skipping this is the most common first-run failure.Pin Playwright to the version the server ships. A bare
npx playwright install chromiumresolves to Playwright's latest release, which can install a Chromium revision the server doesn't support. Resolve the pin first, then install:npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromiumDo not hardcode a version into the user's setup notes — the server auto-updates on each start under npm, so a fixed pin drifts silently. If a scan later fails with
Chromium is not installed. Run npx playwright@<version> install chromium, run that message's command verbatim: it names the version the running server actually expects, which is authoritative over anything precomputed. -
Docker:
docker info(daemon must be running). Chromium ships inside the image, so no browser step is needed.
The package name is unscoped:
axe-mcp-server— not@deque/axe-mcp-server, which does not exist. Only the auth CLI is scoped (@deque/axe-auth). This is an easy mistake to make.
Step 2 — Choose authentication
Ask which method to use (AskUserQuestion):
- API key — simplest. A static
AXE_API_KEY. Best for CI, shared machines, or users who want no extra CLI. - OAuth 2.0 — browser login via the
@deque/axe-authCLI, tokens stored in the OS keychain with automatic refresh. Best for individual developers.
Only one credential at a time. The server fails at startup if both
AXE_API_KEYandAXE_ACCESS_TOKENare set. Configure exactly one; the bundled config enforces this automatically (OAuth token if present, otherwise API key).
API key path
- Direct the user to create a key: Axe Account Portal (https://axe.deque.com) -> API Keys -> ADD NEW API KEY -> product "Axe MCP Server", then copy it.
- Have the user export it where their client can read it:
export AXE_API_KEY="<key>"(persist in shell profile). Never write the key into a committed file.
OAuth path
- Log in:
npx -y @deque/axe-auth login(add--server <url>for private cloud / on-prem). This opens a browser for the PKCE flow and stores tokens in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Requires Node 22 LTS+. - Verify a token can be minted:
npx -y @deque/axe-auth tokenshould print a token. Logout later withnpx -y @deque/axe-auth logout.
npm + OAuth needs an explicit
unset. Under Docker, credentials are passed with explicit-eflags, so an inheritedAXE_API_KEYnever reaches the server. The npm distribution inherits the whole shell environment — so if the user hasAXE_API_KEYexported and an OAuth session, both variables reach the server and it fails at startup. Any npm+OAuth config mustunset AXE_API_KEYwhen it setsAXE_ACCESS_TOKEN. The bundled config does this.
Step 3 — Choose the client
Ask which client to configure (or use $1): Claude Code, Cursor, VS Code (Copilot), Claude Desktop, or generic/other.
The plugin already ships an auth-agnostic .mcp.json (see plugin root) built on the npm distribution — it is not distribution-agnostic, so a user who chose Docker still needs a config from references/client-configs.md. It clears any inherited AXE_ACCESS_TOKEN, mints a fresh one, and passes exactly one credential: AXE_ACCESS_TOKEN if an OAuth session exists (unsetting AXE_API_KEY), otherwise whatever AXE_API_KEY is in the environment. For Claude Code users who chose npm, installing the plugin is usually enough — confirm the server appears and skip to verification.
For every other combination, emit the correct configuration snippet. Read references/client-configs.md and produce the snippet matching the chosen client + distribution + auth method, then either write it to the client's config file (with the user's confirmation) or print it for them to paste.
Merge, do not clobber. Before writing any client config file, read it if it exists and merge the axe-mcp-server entry into the existing mcpServers (or servers for VS Code) object — never overwrite a file that already defines other MCP servers. If unsure, print the snippet for the user to paste instead of writing.
Windows note: the OAuth snippets wrap the command in sh -c, which is unavailable in a stock Windows shell. On Windows, prefer the API-key shape, or have the user run under Git Bash/WSL. This applies to both distributions.
Step 4 — Optional configuration
Mention these only if relevant to the user's situation (full table in references/client-configs.md):
- Private cloud / on-prem / regional SaaS: set
AXE_SERVER_URL(defaulthttps://axe.deque.com) in the same environment as the MCP config, and pass--server <url>toaxe-auth login. - Advanced Rules confidence:
AXE_ADVANCED_RULES(precise|balanced|thorough|disabled) sets the default for every scan this server runs; defaults to the organization's setting. Only worth configuring if the user wants a standing default — individual scans override it with theadvancedRulesparameter, so a one-off ("scan with advanced rules disabled") needs no config change. Ifanalyzehas noadvancedRulesparameter and scans reportsource: "tier_locked"or"unavailable", Advanced Rules are not enabled for the account — a subscription matter, not a misconfiguration. - Custom Chromium (npm only):
AXE_CHROME_PATHpoints at a Chrome for Testing / Chromium binary instead of the Playwright-managed one. It fails at startup under Docker — never set it in a Docker config. Branded Google Chrome stable 137+ is not supported. - Slow pages / verbose logs:
BROWSER_TIMEOUT_MS(default30000),LOG_LEVEL(debug|info|warn|error, defaultinfo).
Step 5 — Verify
Confirm the connection works before declaring success:
- Claude Code: advise running
/mcpand confirmingaxe-mcp-serveris listed and connected. Then run a smokeanalyzeagainst a known URL (e.g.https://dequeuniversity.com/demo/mars). - Other clients: have the user restart/reload the client, open the MCP/tools panel, confirm the axe tools (
analyze,igt,remediate) appear, then run a smokeanalyze.
A successful smoke scan on a real page returns a sizable payload (tens of KB) — that is expected, not an error. If the client complains the result is too large, scope the scan with analyze's selector parameter.
If verification fails, consult the troubleshooting section of references/client-configs.md — it is split by distribution, since the common failure modes differ.
Step 6 — Suggest next steps
Once connected, recommend:
/axe-accessibility:mcp-generate-instructionsto bake the analyze -> remediate -> verify workflow into the repo's agent instructions./axe-accessibility:mcp-audit <url>to run the full remediation loop on a page.
Additional resources
references/client-configs.md— per-client config snippets for all four distribution/auth combinations, the full environment-variable table, and distribution-specific troubleshooting.