Choosing a Distribution
The axe MCP Server ships in two distributions. Both expose the same analyze, remediate, and igt tools and respect the same configuration — they differ only in how the server runs on your machine. Pick whichever fits your environment; neither is preferred.
Both distributions assume you can reach the public registries, npmjs.org and Docker Hub. If your network restricts access to them, see Installing from Deque's Agora instead.
Docker vs. npm
| Docker | npm | |
|---|---|---|
| Runtime | A Docker container | A Node.js process on your host, launched on demand with npx |
| Browser | Bundled in the image | Install Chromium via Playwright, or point at an existing Chrome/Chromium binary you already have |
| Prerequisite | Docker installed and running | Node.js 22.19.0 or later |
Reaching localhost |
Needs --add-host; see ERR_CONNECTION_REFUSED |
Reaches host localhost services directly |
| Best when | You already use Docker and want a self-contained environment | You can't run Docker, or prefer a lighter-weight local process |
Docker
Pull the image initially, and any time you want to move to a newer release:
docker pull dequesystems/axe-mcp-server:latestThat's the only install step — your MCP client launches the container on demand using the configuration in your client setup guide.
npm
There is no separate install step for the server itself — npx -y axe-mcp-server downloads and runs it on demand, and your MCP client invokes that command for you (see your client setup guide).
The npm distribution runs on Node.js and requires 22.19.0 or later. An active Node.js LTS release satisfies this, but an older Node 22 patch release may not.
Install Chromium
Because the server drives a real browser to run scans, you must install a matching Chromium build yourself via Playwright:
npx playwright@$(npm view axe-mcp-server dependencies.playwright) install chromiumThis derives the pin from the published package, so it stays correct as the server updates. Playwright must be pinned: a bare npx playwright install chromium resolves to Playwright's latest release, which can install a Chromium revision the server doesn't support.
Pinned to an older axe-mcp-server, or offline? The command above reads the dependency of the latest published release. If you run a pinned older version, substitute its Playwright version instead — npm view axe-mcp-server@<version> dependencies.playwright — or take it from the Chromium startup error, which names the exact command for the server you are actually running. At the time of writing, server version 1.4.0 ships Playwright 1.61.1.
On Windows cmd.exe, which has no $(...) substitution, run npm view axe-mcp-server dependencies.playwright on its own and paste the version into the command. PowerShell, Git Bash, and WSL handle the command as written.
See Troubleshooting Chromium Installation if the versions drift.
On Linux, you may also need the system libraries Chromium depends on. See Troubleshooting Chromium Installation for details.
Alternative: use a browser you already have
If you already have a compatible Chrome/Chromium binary on your machine, you can skip the Playwright install and point the server at it instead by setting the AXE_CHROME_PATH environment variable. This is available only with the npm distribution — the Docker image always uses its bundled browser. See AXE_CHROME_PATH for requirements and caveats.
Next steps
- Set up authentication — an API key or OAuth 2.0
- Configure your client — VS Code with Copilot, Cursor, or Claude Code