Accessibility MCP Server

How to use

You use an MCP client to connect to the Accessibility Scanner as either a local (stdio) server or a remote (http) server. In practice, you start the server in your environment and then issue commands to navigate pages, perform interactions, capture snapshots, and run accessibility scans. Focus on practical workflows such as loading a page, inspecting accessibility violations, and generating reports with remediation guidance.

How to install

Prerequisites: ensure you have Node.js installed on your system. You will run commands from a terminal or shell.

Install the MCP Accessibility Scanner globally using npm:

npm install -g mcp-accessibility-scanner

Configuration

Configure the MCP client to run the scanner as an MCP server. The following configuration snippet shows how to wire the scanner as a stdio MCP server using npx.

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

Advanced configuration

You can pass a configuration file to customize Playwright behavior. The following option demonstrates how to start the scanner with a config file path.

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

Configuration options you can place in config.json

Create a config.json with the options shown to tailor browser behavior, timeouts, and network rules.

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": true,
      "channel": "chrome"
    }
  },
  "timeouts": {
    "navigationTimeout": 60000,
    "defaultTimeout": 5000
  },
  "network": {
    "allowedOrigins": ["example.com", "trusted-site.com"],
    "blockedOrigins": ["ads.example.com"]
  }
}

Usage notes

If you plan to interact with pages programmatically, you can run a sequence that navigates to a URL, performs actions, and then runs an accessibility scan to produce a report.

Usage examples

Basic Accessibility Scan: navigate to a page, then run a scan to check WCAG 2.1 AA violations.

Color contrast check: load the page and run a scan filtered to color-related categories.

Troubleshooting and notes

Most interactions rely on a snapshot of the page to resolve element references. Capture a snapshot before attempting element-based actions to ensure you have accurate references.

Security and best practices

Limit network access where appropriate and use the allowedOrigins/blockedOrigins settings to restrict where the scanner can load resources. Keep dependencies up to date and review generated reports for remediation guidance.

scan_page

Performs a comprehensive accessibility scan on the current page using Axe-core. Parameters include violationsTag to filter which WCAG categories or sections to check.

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.

browser_snapshot

Capture an accessibility snapshot of the current page for element analysis.

browser_click

Click on a page element. Parameters: element, ref, doubleClick (optional).

browser_type

Type text into an editable element. Parameters: element, ref, text, submit (optional), slowly (optional).

browser_hover

Hover over an element on the page. Parameters: element, ref.

browser_drag

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').

browser_take_screenshot

Take a screenshot of the current page. Parameters: raw, filename, element, ref.

browser_pdf_save

Save the current page as a PDF. Parameters: filename.

browser_close

Close the current page.

browser_resize

Resize the browser window. Parameters: width, height.

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 by index (or current if not provided).

browser_console_messages

Return all console messages from the page.

browser_network_requests

Return all network requests since the page load.

browser_wait_for

Wait for text to appear or disappear or for a time delay. Parameters: time, text, textGone.

browser_handle_dialog

Handle browser dialogs. Parameters: accept, promptText (optional).

browser_file_upload

Upload files to the page. Parameters: paths (array of absolute file paths).

browser_screen_capture

Coordinate-based screenshot for vision mode interactions.

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 in coordinate-based mode. Parameters: text, submit (optional).