Skip to main content
Glama
MCP Accessibility Scanner

MCP Accessibility Scanner

by JustasMonkev

MCP Accessibility Scanner 🔍

Star History

Star History Chart

A powerful Model Context Protocol (MCP) server that provides automated web accessibility scanning and browser automation using Playwright and Axe-core. This server enables LLMs to perform WCAG compliance checks, interact with web pages, manage persistent browser sessions, and generate detailed accessibility reports with visual annotations.

Related MCP server: Accessibility Testing MCP

Features

Accessibility Scanning

✅ Full WCAG 2.0/2.1/2.2 compliance checking (A, AA, AAA levels)
📄 Detailed JSON reports with remediation guidance
🎯 Support for specific violation categories (color contrast, ARIA, forms, keyboard navigation, etc.)

Browser Automation

🖱️ Click, hover, and drag elements using accessibility snapshots
⌨️ Type text and handle keyboard inputs
🔍 Capture page snapshots to discover all interactive elements
📸 Take screenshots and save PDFs
🎯 Support for both element-based and coordinate-based interactions

Advanced Features

📑 Tab management for multi-page workflows
🌐 Monitor console messages and network requests
⏱️ Wait for dynamic content to load
📁 Handle file uploads and browser dialogs
🔄 Navigate through browser history

Installation

You can install the package using any of these methods:

Using npm:

npm install -g mcp-accessibility-scanner

Installation with Docker

A pre-built image is available on Docker Hub. The image includes Chromium and is pre-configured for containerized use — no extra flags needed.

Pull from Docker Hub:

docker pull justasmonkev/mcp-accessibility-scanner

Claude Code

 claude mcp add mcp-accessibility-scanner -s user -- docker run -i --rm justasmonkev/mcp-accessibility-scanner

To persist screenshots and reports on your host, add a volume mount:

claude mcp add mcp-accessibility-scanner -s user \
  -- docker run -i --rm -v /tmp/mcp-output:/app/output justasmonkev/mcp-accessibility-scanner

Without the -v mount, output files only exist inside the container and are lost when it exits.

Docker Compose

docker compose up -d

Build from source

docker build -t mcp-accessibility-scanner .

Docker smoke test

npm run test:docker

Installation in VS Code

Install the Accessibility Scanner in VS Code using the VS Code CLI:

For VS Code:

code --add-mcp '{"name":"accessibility-scanner","command":"npx","args":["mcp-accessibility-scanner"]}'

For VS Code Insiders:

code-insiders --add-mcp '{"name":"accessibility-scanner","command":"npx","args":["mcp-accessibility-scanner"]}'

CLI Modes

The scanner can run in two modes depending on how you use it.

MCP server (default, no subcommand)

When launched without a subcommand, the process starts an MCP server that communicates over stdio. This is the mode used by MCP clients such as Claude Desktop, VS Code, and Claude Code -- you should never need to run it by hand.

npx mcp-accessibility-scanner            # starts the MCP server (stdio)

All of the MCP client configuration examples in this README already use this default mode.

Interactive REPL (interactive subcommand)

For manual terminal use, the interactive subcommand starts a readline REPL where you can call any tool directly:

$ npx mcp-accessibility-scanner interactive
Interactive mode. Type "<tool-name> <json>" to call a tool. Ctrl+D to exit.
> browser_navigate {"url": "https://example.com"}
> scan_page {"violationsTag": ["wcag21aa"]}
> audit_keyboard {"maxTabs": 30}

Each line is <tool-name> <json-arguments>. Omit the JSON to pass {}. Global browser connection flags still apply here, for example npx mcp-accessibility-scanner --extension interactive.

Discovering available tools (list-tools subcommand)

To print every tool name and its description:

npx mcp-accessibility-scanner list-tools

Note: Tool names like browser_navigate and scan_page are MCP tool identifiers (and REPL commands in interactive mode). They are not shell subcommands -- you cannot run npx mcp-accessibility-scanner browser_navigate.

Configuration

Here's the Claude Desktop configuration:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["-y", "mcp-accessibility-scanner"]
    }
  }
}

Advanced Configuration

You can pass a configuration file to customize Playwright behavior:

{
  "mcpServers": {
    "accessibility-scanner": {
      "command": "npx",
      "args": ["-y", "mcp-accessibility-scanner", "--config", "/path/to/config.json"]
    }
  }
}

Configuration Options

Create a config.json file with the following options:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": true,
      "channel": "chrome"
    },
    "cdpLaunch": {
      "command": "open",
      "args": ["-a", "Slack", "--args", "--remote-debugging-port={port}"],
      "startupTimeoutMs": 30000
    }
  },
  "timeouts": {
    "navigationTimeout": 60000,
    "defaultTimeout": 5000
  },
  "network": {
    "allowedOrigins": ["example.com", "trusted-site.com"],
    "blockedOrigins": ["ads.example.com"]
  }
}

Available Options:

  • browser.browserName: Browser to use (chromium, firefox, webkit)

  • browser.launchOptions.headless: Run browser in headless mode (default: true on Linux without display, false otherwise)

  • browser.launchOptions.channel: Browser channel (chrome, chrome-beta, msedge, etc.)

  • browser.cdpEndpoint: Attach to an already-running Chromium-family app with CDP enabled

  • browser.cdpLaunch: Launch a Chromium-family desktop app with CDP enabled, wait for the endpoint, and manage the child process lifecycle

  • timeouts.navigationTimeout: Maximum time for page navigation in milliseconds (default: 60000)

  • timeouts.defaultTimeout: Default timeout for Playwright operations in milliseconds (default: 5000)

  • network.allowedOrigins: List of origins to allow (blocks all others if specified)

  • network.blockedOrigins: List of origins to block

CLI equivalents are also available: --cdp-launch-command, --cdp-launch-args, --cdp-launch-cwd, --cdp-launch-port, and --cdp-launch-startup-timeout.

Available Tools

The MCP server provides comprehensive browser automation and accessibility scanning tools:

Core Accessibility Tool

scan_page

Performs a comprehensive accessibility scan on the current page using Axe-core.

Parameters:

  • violationsTag: Array of WCAG/violation tags to check

Supported Violation Tags:

  • WCAG standards: wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, wcag22aaa

  • Section 508: section508

  • Categories: cat.aria, cat.color, cat.forms, cat.keyboard, cat.language, cat.name-role-value, cat.parsing, cat.semantics, cat.sensory-and-visual-cues, cat.structure, cat.tables, cat.text-alternatives, cat.time-and-media

Audit Tools

audit_site

Crawls and scans multiple internal pages, then aggregates violations across the site.

  • Default strategy: link-based BFS from the current URL

  • Supports links, nav, sitemap, and provided URL strategies

  • Always writes a JSON report (default filename: audit-site-{timestamp}.json)

Example flow:

1. Navigate to your site homepage with browser_navigate
2. Run audit_site with maxPages: 25 and maxDepth: 2
3. Review the report path returned by the tool (written to the MCP output directory)

scan_page_matrix

Runs Axe scans on the same page across viewport/media/zoom variants and compares deltas against baseline.

  • Default variants: baseline, mobile, desktop, forced-colors, reduced-motion, zoom-200

  • Supports custom variants and optional reload between variants

  • Always writes a JSON report (default filename: scan-matrix-{timestamp}.json)

Example flow:

1. Navigate to a page state you want to validate
2. Run scan_page_matrix with defaults (or provide custom variants)
3. Review per-variant deltas and open the generated JSON report path

audit_keyboard

Audits real keyboard focus behavior by pressing Tab (and optional Shift+Tab) with practical heuristics.

  • Checks skip links, focus visibility, focus jumps, and possible focus traps

  • Optional issue screenshots (screenshotOnIssue)

  • Always writes a JSON report (default filename: audit-keyboard-{timestamp}.json)

Example flow:

1. Navigate to the target page and let it fully load
2. Run audit_keyboard with maxTabs: 50
3. Review focus findings and open the generated JSON report path

Navigation Tools

browser_navigate

Navigate to a URL.

  • Parameters: url (string)

browser_navigate_back

Go back to the previous page.

browser_navigate_forward

Go forward to the next page.

Page Interaction Tools

browser_snapshot

Capture accessibility snapshot of the current page (better than screenshot for analysis).

browser_click

Perform click on a web page element.

  • Parameters: element (description), ref (element reference), doubleClick (optional)

browser_type

Type text into editable element.

  • Parameters: element, ref, text, submit (optional), slowly (optional)

browser_hover

Hover over element on page.

  • Parameters: element, ref

browser_drag

Perform drag and drop between two elements.

  • Parameters: startElement, startRef, endElement, endRef

browser_select_option

Select an option in a dropdown.

  • Parameters: element, ref, values (array)

browser_press_key

Press a key on the keyboard.

  • Parameters: key (e.g., 'ArrowLeft' or 'a')

Screenshot & Visual Tools

browser_take_screenshot

Take a screenshot of the current page.

  • Parameters: raw (optional), filename (optional), element (optional), ref (optional)

browser_pdf_save

Save page as PDF.

  • Parameters: filename (optional, defaults to page-{timestamp}.pdf)

Browser Management

browser_close

Close the page.

browser_resize

Resize the browser window.

  • Parameters: width, height

Tab Management

browser_tab_list

List all open browser tabs.

browser_tab_new

Open a new tab.

  • Parameters: url (optional)

browser_tab_select

Select a tab by index.

  • Parameters: index

browser_tab_close

Close a tab.

  • Parameters: index (optional, closes current tab if not provided)

Information & Monitoring Tools

browser_console_messages

Returns all console messages from the page.

browser_network_requests

Returns all network requests since loading the page.

Utility Tools

browser_wait_for

Wait for text to appear/disappear or time to pass.

  • Parameters: time (optional), text (optional), textGone (optional)

browser_handle_dialog

Handle browser dialogs (alerts, confirms, prompts).

  • Parameters: accept (boolean), promptText (optional)

browser_file_upload

Upload files to the page.

  • Parameters: paths (array of absolute file paths)

Vision Mode Tools (Coordinate-based Interaction)

browser_screen_capture

Take a screenshot for coordinate-based interaction.

browser_screen_move_mouse

Move mouse to specific coordinates.

  • Parameters: element, x, y

browser_screen_click

Click at specific coordinates.

  • Parameters: element, x, y

browser_screen_drag

Drag from one coordinate to another.

  • Parameters: element, startX, startY, endX, endY

browser_screen_type

Type text (coordinate-independent).

  • Parameters: text, submit (optional)

Usage Examples

Basic Accessibility Scan

1. Navigate to example.com using browser_navigate
2. Run scan_page with violationsTag: ["wcag21aa"]

Color Contrast Check

1. Use browser_navigate to go to example.com
2. Run scan_page with violationsTag: ["cat.color"]

Multi-step Workflow

1. Navigate to example.com with browser_navigate
2. Take a browser_snapshot to see available elements
3. Click the "Sign In" button using browser_click
4. Type "user@example.com" using browser_type
5. Run scan_page on the login page
6. Take a browser_take_screenshot to capture the final state

Page Analysis

1. Navigate to example.com
2. Use browser_snapshot to capture all interactive elements
3. Review console messages with browser_console_messages
4. Check network activity with browser_network_requests

Tab Management

1. Open a new tab with browser_tab_new
2. Navigate to different pages in each tab
3. Switch between tabs using browser_tab_select
4. List all tabs with browser_tab_list

Waiting for Dynamic Content

1. Navigate to a page
2. Use browser_wait_for to wait for specific text to appear
3. Interact with the dynamically loaded content

Note: Most interaction tools require element references from browser_snapshot. Always capture a snapshot before attempting to interact with page elements.

Development

Clone and set up the project:

git clone https://github.com/JustasMonkev/mcp-accessibility-scanner.git
cd mcp-accessibility-scanner
npm install

License

MIT

Available Tools

25 tools
browser_clickB
Destructive

Perform click on a web page

Inputs: element (required), ref (required), doubleClick.

browser_closeB
Read-only

Close the page

Inputs: no named parameters.

browser_console_messagesA
Read-only

Returns all console messages

Inputs: no named parameters.

browser_dragB
Destructive

Perform drag and drop between two elements

Inputs: endElement (required), endRef (required), startElement (required), startRef (required).

browser_file_uploadB
Destructive

Upload one or multiple files

Inputs: paths (required).

browser_handle_dialogC
Destructive

Handle a dialog

Inputs: accept (required), promptText.

browser_hoverB
Read-only

Hover over element on page

Inputs: element (required), ref (required).

browser_installA
Destructive

Install the browser specified in the config. Call this if you get an error about the browser not being installed.

Inputs: no named parameters.

browser_navigateB
Destructive

Navigate to a URL

Inputs: url (required).

browser_navigate_backA
Read-only

Go back to the previous page

Inputs: no named parameters.

browser_navigate_forwardB
Read-only

Go forward to the next page

Inputs: no named parameters.

browser_network_requestsA
Read-only

Returns all network requests since loading the page

Inputs: no named parameters.

browser_pdf_saveB
Read-only

Save page as PDF

Inputs: filename.

browser_press_keyB
Destructive

Press a key on the keyboard

Inputs: key (required).

browser_resizeB
Read-only

Resize the browser window

Inputs: height (required), width (required).

browser_select_optionB
Destructive

Select an option in a dropdown

Inputs: element (required), ref (required), values (required).

browser_snapshotB
Read-only

Capture accessibility snapshot of the current page, this is better than screenshot

Inputs: no named parameters.

browser_tab_closeC
Destructive

Close a tab

Inputs: index.

browser_tab_listB
Read-only

List browser tabs

Inputs: no named parameters.

browser_tab_newA
Read-only

Open a new tab

Inputs: url.

browser_tab_selectB
Read-only

Select a tab by index

Inputs: index (required).

browser_take_screenshotA
Read-only

Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.

Inputs: element, filename, raw, ref.

browser_typeA
Destructive

Type text into editable element

Inputs: element (required), ref (required), text (required), slowly, +1 more.

browser_wait_forB
Read-only

Wait for text to appear or disappear or a specified time to pass

Inputs: text, textGone, time.

scan_pageB
Destructive

Scan the current page for accessibility violations using Axe

Inputs: violationsTag (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between browser_snapshot and browser_take_screenshot, as both capture page visuals, though their descriptions clarify different use cases. Other tools like browser_navigate, browser_navigate_back, and browser_navigate_forward are clearly differentiated, and actions like click, hover, and type are well-separated.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with a 'browser_' prefix for most tools, except scan_page which still fits the style. The naming is highly predictable, using verb_noun combinations like browser_click, browser_navigate, and browser_tab_list, making it easy to understand and navigate.

    Tool Count3/5

    With 25 tools, the count is borderline high for an accessibility scanner, as it includes many general browser automation functions beyond core accessibility tasks. While comprehensive, it may feel heavy and could be streamlined by focusing more on accessibility-specific operations rather than broad browser control.

    Completeness4/5

    The toolset covers a wide range of browser interactions and includes a dedicated accessibility scanning tool (scan_page), but there are minor gaps such as lacking tools for specific accessibility audits like color contrast checks or ARIA attribute validation. However, the core functionality for navigating, interacting, and scanning pages is well-covered.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to perform comprehensive accessibility audits on websites using Playwright and axe-core against WCAG standards. Provides detailed compliance reports with violation summaries and remediation guidance across multiple browsers.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables comprehensive WCAG 2.0/2.1 accessibility testing of web applications using Playwright and axe-core. Supports natural language element finding, auto-discovery of interactive components, and generates detailed compliance reports with screenshots.
      2
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI coding agents to perform real-browser accessibility scanning of localhost pages using Playwright and axe-core, returning WCAG 2.1 violations with structured fix plans.
      3
      21 npm
      1
      MIT