Playwright Accessibility MCP Server

This project is an implementation of a Model Context Protocol (MCP) server for accessibility testing using Playwright and Axe. It provides tools to scan URLs, raw HTML, and batches of URLs for accessibility violations and summarize the results.

[!TIP] The simplest way to get started is to use the one-line installation: npx playwright-accessibility-mcp-server. This will automatically download and run the latest version without having to manually install the package.

Features

• scan-url: Scans a single URL for accessibility violations.
• scan-html: Scans raw HTML content for accessibility violations.
• scan-batch: Scans multiple URLs for accessibility violations.
• summarize-violations: Summarizes accessibility violations from Axe results.
• write-violations-report: Writes accessibility violations report to the output directory.

Requirements

• Node.js 18 or newer
• VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client

Getting started

First, install the Playwright Accessibility MCP server with your client. A typical configuration looks like this:

{
  "mcpServers": {
    "playwright-accessibility": {
      "command": "npx",
      "args": [
        "playwright-accessibility-mcp-server@latest"
      ]
    }
  }
}

You can also install the Playwright Accessibility MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"playwright-accessibility","command":"npx","args":["playwright-accessibility-mcp-server@latest"]}'

After installation, the Playwright Accessibility MCP server will be available for use with your GitHub Copilot agent in VS Code.

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx playwright-accessibility-mcp-server. You can also verify config or add command like arguments via clicking Edit.

{
  "mcpServers": {
    "playwright-accessibility": {
      "command": "npx",
      "args": [
        "playwright-accessibility-mcp-server@latest"
      ]
    }
  }
}

Follow Windsuff MCP documentation. Use following configuration:

{
  "mcpServers": {
    "playwright-accessibility": {
      "command": "npx",
      "args": [
        "playwright-accessibility-mcp-server@latest"
      ]
    }
  }
}

Follow the MCP install guide, use following configuration:

{
  "mcpServers": {
    "playwright-accessibility": {
      "command": "npx",
      "args": [
        "playwright-accessibility-mcp-server@latest"
      ]
    }
  }
}

Installation

1. Clone the repository:

   git clone https://github.com/deepakkamboj/playwright-accessibility-mcp-server.git
   cd playwright-accessibility-mcp-server

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

🔧 Usage

Starting the Server

1. Start the server:

   npm start

2. Use the tools via the MCP protocol to perform accessibility testing.

Using as an MCP Server

This project implements the MCP protocol, allowing you to interact with the server using MCP-compatible clients. Below are the steps to use it as an MCP server:

1. Start the MCP Server: Ensure the server is running by executing:

   npm start

2. Connect to the Server: Use an MCP client to connect to the server. The default server runs on http://localhost:3000.

3. Send MCP Requests: Use the following tools via MCP requests:

   • scan-url: Analyze a single URL for accessibility violations.
   • scan-html: Analyze raw HTML content for accessibility violations.
   • scan-batch: Analyze multiple URLs for accessibility violations.
   • summarize-violations: Summarize accessibility violations from Axe results.
   • write-violations-report: Write accessibility violations report to the output directory.

4. Example MCP Request: Below is an example of an MCP request to write a violations report:

   {
     "tool": "write-violations-report",
     "input": {
       "violations": [
         {
           "id": "color-contrast",
           "impact": "serious",
           "description": "Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds.",
           "helpUrl": "https://dequeuniversity.com/rules/axe/4.7/color-contrast",
           "nodes": [
             {
               "target": ["#example"],
               "failureSummary": "Fix this element's color contrast.",
               "html": "<div id='example' style='color: #fff; background-color: #fff;'>Example</div>"
             }
           ]
         }
       ]
     }
   }

   Send this request to the server using an MCP client, and the server will write the violations report to the output directory.

MCP (JSON‑RPC) Mode

For AI clients (e.g. Claude Desktop, Cursor, VS Code MCP extension), configure your <client>_config.json:

{
  "mcpServers": {
    "playwright-accessibility-mcp-server": {
      "command": "node",
      "args": ["${AbsolutePath}/build/index.js"]
    }
  }
}

Once the MCP server is running, you can invoke tools like:

• scan-url (params: { "url": "https://google.com" })
• scan-html (params: { "html": "<h1>Hello</h1>" })
• scan-batch (params: { "urls": ["https://a.com","https://b.com"] })
• summarize-violations (params: { "result": <axe result> })

MCP Local Dev Mode

For local development, configure your <client>_config.json as follows:

{
  "mcpServers": {
    "playwright-accessibility-mcp-server": {
      "command": "node",
      "args": ["${AbsolutePath}/build/index.js"]
    }
  }
}

Development

• To run the server in development mode:

  npm run dev

• To test the tools, export the server and use the MCP SDK.

🤝 Contributing

1. Fork the repo.
2. Create a branch (git checkout -b feature/xyz).
3. Commit your changes.
4. Open a Pull Request (PR).

License

This project is licensed under the MIT License.