Web Accessibility-Testing MCP Server (A11y MCP)

Web 无障碍测试 MCP 服务（A11y MCP）

https://github.com/user-attachments/assets/316c6d44-e677-433e-b4d5-63630b4bab2b

A11y MCP 是一个 MCP（模型上下文协议） 服务，可让大模型使用 Web 无障碍测试 API。

此服务使用 Deque Axe-core API 和 Puppeteer，让大模型能够分析 Web 内容是否符合 WCAG 标准，并发现无障碍问题。

注意： 这不是 Deque Labs 官方提供的 MCP 服务。

功能

• 测试网页：测试任意公开 URL 的无障碍问题，并可自定义视口尺寸
• 测试 HTML 片段：测试原始 HTML 字符串中的无障碍问题
• WCAG 合规性测试：根据不同的 WCAG 标准（2.0、2.1、2.2）检查内容
• 自定义测试：指定要测试的无障碍标签／标准
• 规则探索：获取可用无障碍规则的信息
• 色彩对比度分析：检查色彩组合是否符合 WCAG 标准
• ARIA 验证：测试 ARIA 属性的使用是否正确
• 屏幕方向锁定检测：识别强制使用特定屏幕方向的内容

安装

前置条件

• Node.js 18 或更高版本
• 兼容 MCP 的客户端（Claude Desktop、Claude Code、VS Code、Cursor 等）

Claude Desktop

编辑 MCP 配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

将服务添加到 mcpServers 对象中：

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

Claude Code（CLI）

claude mcp add a11y-accessibility -- npx -y a11y-mcp-server

这会为当前项目注册此服务。若要在所有项目中使用：

claude mcp add --scope user a11y-accessibility -- npx -y a11y-mcp-server

验证服务是否已注册：

claude mcp list

注意： 重启 Claude Code 会话后，MCP 工具才会生效。

VS Code（Copilot）

将配置添加到 VS Code 的 settings.json 或 .vscode/settings.json：

{
  "mcp": {
    "servers": {
      "a11y-accessibility": {
        "command": "npx",
        "args": ["-y", "a11y-mcp-server"]
      }
    }
  }
}

Cursor

将配置添加到 Cursor 的 MCP 配置文件（.cursor/mcp.json）：

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

Windsurf

将配置添加到 Windsurf 的 MCP 配置文件（~/.codeium/windsurf/mcp_config.json）：

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

可用工具

test_accessibility

测试 URL 是否存在无障碍问题。

参数：

参数	必填	描述
url	是	要测试的网页 URL
tags	否	要测试的 WCAG 标签数组（例如，["wcag2aa"]）
width	否	视口宽度，单位为像素（默认值：1280）
height	否	视口高度，单位为像素（默认值：800）

示例 — 桌面视口（默认）：

{
  "url": "https://example.com",
  "tags": ["wcag2aa"]
}

示例 — 移动视口（iPhone 12/13）：

{
  "url": "https://example.com",
  "tags": ["wcag2aa"],
  "width": 390,
  "height": 844
}

test_html_string

检查 HTML 字符串中的无障碍问题。

参数：

参数	必填	描述
html	是	要检查的 HTML 内容
tags	否	要检查的 WCAG 标签数组（例如，["wcag2aa"]）
width	否	视口宽度（像素；默认值：1280）
height	否	视口高度（像素；默认值：800）

示例 — 默认视口：

{
  "html": "<div><img src='image.jpg'></div>",
  "tags": ["wcag2aa"]
}

示例 — 移动视口：

{
  "html": "<div><img src='image.jpg'></div>",
  "tags": ["wcag2aa"],
  "width": 375,
  "height": 812
}

get_rules

获取可用无障碍规则的信息，可选择筛选条件。返回规则对象数组，每个对象包含 ruleId、description、help、helpUrl 和 tags。

参数：

参数	必填	描述
tags	否	按标签筛选规则（例如，["wcag2a", "wcag2aa", "best-practice"]）

示例 — 按 WCAG 2.1 AA 筛选规则：

{
  "tags": ["wcag21aa"]
}

示例 — 获取所有规则（不筛选）：

{}

check_color_contrast

检查前景色与背景色的组合是否符合 WCAG 对比度要求。

参数：

参数	必填	描述
foreground	是	前景色（例如，"#000000"、"rgb(0,0,0)"）
background	是	背景色（例如，"#FFFFFF"、"rgb(255,255,255)"）
fontSize	否	字体大小（像素；默认值：16）
isBold	否	文本是否为粗体（默认值：false）

示例：

{
  "foreground": "#777777",
  "background": "#EEEEEE",
  "fontSize": 16,
  "isBold": false
}

check_aria_attributes

检查 HTML 中的 ARIA 属性使用是否正确。

参数：

参数	必填	描述
html	是	要检查 ARIA 属性使用情况的 HTML 内容

示例：

{
  "html": "<div role='button' aria-pressed='false'>Click me</div>"
}

check_orientation_lock

检查内容是否强制采用特定方向。

参数：

参数	必填	描述
html	是	要检查方向锁定问题的 HTML 内容

示例：

{
  "html": "<html><head><meta name='viewport' content='width=device-width, orientation=portrait'></head><body>Content</body></html>"
}

响应格式

服务以结构化 JSON 格式返回无障碍测试结果：

{
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds",
      "help": "Elements must meet minimum color contrast ratio thresholds",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast",
      "affectedNodes": [
        {
          "html": "<div style=\"color: #aaa; background-color: #eee;\">Low contrast text</div>",
          "target": ["div"],
          "failureSummary": "Fix any of the following: Element has insufficient color contrast of 1.98 (foreground color: #aaa, background color: #eee, font size: 12.0pt, font weight: normal)"
        }
      ]
    }
  ],
  "passes": 1,
  "incomplete": 0,
  "inapplicable": 2,
  "timestamp": "2025-04-25T16:45:33.655Z",
  "url": "about:blank",
  "testEngine": {
    "name": "axe-core",
    "version": "4.10.3"
  }
}

WCAG 标签参考

可用于 tags 参数的常见标签：

标签	描述
wcag2a	WCAG 2.0 A 级
wcag2aa	WCAG 2.0 AA 级
wcag2aaa	WCAG 2.0 AAA 级
wcag21a	WCAG 2.1 A 级
wcag21aa	WCAG 2.1 AA 级
wcag22aa	WCAG 2.2 AA 级
best-practice	最佳实践（不严格属于 WCAG）

依赖项

• @modelcontextprotocol/sdk
• puppeteer
• @axe-core/puppeteer
• axe-core

许可证

MIT