deepakkamboj/playwright-accessibility-mcp-server

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"
      ]
    }
  }
}

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

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

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

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

𝗪𝗵𝘆 𝗔𝗰𝗰𝗲𝘀𝘀𝗶𝗯𝗶𝗹𝗶𝘁𝘆 𝗧𝗲𝘀𝘁𝗶𝗻𝗴 𝗠𝗮𝘁𝘁𝗲𝗿𝘀:

Accessibility testing ensures that digital content is usable by people with disabilities. It promotes inclusivity and compliance with standards like WCAG. By integrating accessibility testing into your workflow, you can create a better user experience for everyone. 🌍

𝗪𝗵𝘆 𝗣𝗹𝗮𝘆𝘄𝗿𝗶𝗴𝗵𝘁 𝗔𝗰𝗰𝗲𝘀𝘀𝗶𝗯𝗶𝗹𝗶𝘁𝘆 𝗠𝗮𝘁𝘁𝗲𝗿𝘀:

Accessibility testing ensures that digital content is usable by people with disabilities. It promotes inclusivity and compliance with standards like WCAG. By integrating Playwright accessibility testing into your workflow, you can:

• 📌𝗘𝗻𝗵𝗮𝗻𝗰𝗲 𝗨𝘀𝗲𝗿 𝗘𝘅𝗽𝗲𝗿𝗶𝗲𝗻𝗰𝗲: Make your applications usable for everyone, including people with disabilities.
• 📌𝗘𝗻𝘀𝘂𝗿𝗲 𝗖𝗼𝗺𝗽𝗹𝗶𝗮𝗻𝗰𝗲: Meet legal and regulatory requirements for accessibility.
• 📌𝗣𝗿𝗼𝗺𝗼𝘁𝗲 𝗜𝗻𝗰𝗹𝘂𝘀𝗶𝘃𝗶𝘁𝘆: Foster an inclusive digital environment where everyone can access and benefit from your content.

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.