https://github.com/vinnyang/axe-scanner-mcp
A standalone Model Context Protocol server that runs axe accessibility scans for a supplied URL using Playwright.
https://github.com/vinnyang/axe-scanner-mcp
a11y axe axe-core mcp mcp-server playwright typescript web-accessibility-tool
Last synced: about 1 month ago
JSON representation
A standalone Model Context Protocol server that runs axe accessibility scans for a supplied URL using Playwright.
- Host: GitHub
- URL: https://github.com/vinnyang/axe-scanner-mcp
- Owner: vinnyang
- Created: 2025-11-18T21:12:56.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-11-19T02:33:13.000Z (7 months ago)
- Last Synced: 2025-11-19T04:16:21.287Z (7 months ago)
- Topics: a11y, axe, axe-core, mcp, mcp-server, playwright, typescript, web-accessibility-tool
- Language: TypeScript
- Homepage:
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Axe Scanner MCP Server [](https://smithery.ai/server/@vinnyang/axe-scanner-mcp)
A standalone Model Context Protocol server that runs axe accessibility scans for a supplied URL using Playwright.
## Screenshot
## Prerequisites
- Node.js 18 or newer
- Playwright browsers (`npx playwright install`), plus system dependencies if required (`npx playwright install --with-deps` on macOS/Linux)
## Installation
```bash
npm install
npm run build
```
## Setting up with MCP Clients
This configuration works with all MCP-compatible clients (Claude Desktop, Cursor, etc.). Add the following to your MCP client configuration:
**Using node:**
```json
{
"mcpServers": {
"axe-scanner-mcp": {
"command": "node",
"args": ["/absolute/path/to/axe-scanner-mcp/dist/index.js"]
}
}
}
```
**Using npx:**
```json
{
"mcpServers": {
"axe-scanner-mcp": {
"command": "npx",
"args": ["-y", "/absolute/path/to/axe-scanner-mcp"]
}
}
}
```
**Note:**
- Use absolute paths in your configuration
- Configuration file locations:
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor:** Settings → Features → Model Context Protocol
- Restart your MCP client after adding the server configuration
## Usage
### Running the MCP Server
You can run the server in several ways:
**Using npm scripts (recommended for development):**
```bash
npm start
```
Or run in development mode with automatic restart on file changes:
```bash
npm run dev
```
The `dev` script watches for changes in the source files and automatically restarts the server.
**Using npx:**
After building the package (`npm run build`), you can run it with npx:
```bash
# Using the local path
npx /absolute/path/to/axe-scanner-mcp
# Or link it locally first for easier access
npm link
npx axe-scanner-mcp
# Or install it in another project
npm install /absolute/path/to/axe-scanner-mcp
npx axe-scanner-mcp
```
**Using node directly:**
```bash
node dist/index.js
```
Run a one-off scan from the CLI:
```bash
npm run scan -- https://example.com
```
### Registered tool
`axe_scan_url`
Runs an axe accessibility scan and returns both a summary and the full axe results JSON.
Input arguments:
- `url` (string, required): Page to scan.
- `tags` (string[], optional, defaults to `["wcag2a"]`): Restrict analysis to specific tags. Leave empty to disable tag filtering.
- `runOnlyRules` (string[], optional): Restrict analysis to specific rule IDs. Cannot be combined with `tags`.
- `disableRules` (string[], optional): Skip specific rule IDs.
- `includeSelectors` (string[], optional): CSS selectors to scope the scan.
- `excludeSelectors` (string[], optional): CSS selectors to omit from the scan.
- `waitUntil` (`"load" | "domcontentloaded" | "networkidle" | "commit"`, optional): Navigation lifecycle to await. Defaults to `load`.
- `navigationTimeoutMs` (number, optional): Playwright navigation timeout in milliseconds.
- `legacyMode` (boolean, optional): Whether to run axe in legacy mode to avoid blank-page aggregation (disables cross-origin frame testing).
- `viewport` (object, optional): Override viewport `width`, `height`, `deviceScaleFactor`, and/or `userAgent`. Defaults to 1280×720 / DPR 1 / Playwright default UA.
- `browser` (`"chromium" | "firefox" | "webkit"`, optional): Browser engine to launch. Defaults to `chromium`.
- `headless` (boolean, optional): Run the browser in headless mode. Defaults to `true`.
- `postNavigationWaitMs` (number, optional): Milliseconds to wait after navigation (and optional selector wait) before running axe. Defaults to `1000`.
- `waitForSelector` (string, optional): CSS selector to wait for before the post-navigation delay.
- `axeOptions` (object, optional): Raw options passed to `axe.configure` via `builder.options(...)`.
- `includeSummary` (boolean, optional): When `true`, adds a short human-readable summary string alongside the full JSON payload. Defaults to `false`.
## Development
**Development mode with watch:**
The `dev` script automatically watches for file changes and restarts the server:
```bash
npm run dev
```
**Manual rebuild:**
To rebuild the project manually:
```bash
npm run build
```
Format of the tool response:
- `success`: indicates execution status.
- `url`: scanned URL.
- `summary`: counts of violations, passes, incomplete, and inapplicable rule results.
- `analysis`: raw axe results returned by `@axe-core/playwright`.