Opens pull requests on GitHub repositories via Octokit.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-a11y Audit https://example.com, fix issues, and open a PR."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The USB-C port of accessibility: one MCP server that audits any web page against WCAG and applies fixes, drivable from any MCP client (Claude Desktop, etc.).
Web accessibility is a solved science (WCAG tells you exactly what is broken) but a chronic practice. Every team rebuilds the same audit-and-fix loop, glued to one framework or one CI vendor, behind one proprietary dashboard. The knowledge does not travel.
mcp-a11y turns that loop into a standard interface. Detection stays 100% deterministic (axe-core decides what is broken, never a model). The only place a model is used is to describe images for alt text. Any MCP client can plug in, audit a page, get deterministic fixes back, and open a mergeable PR. That is the thesis: a universal, boring, reliable port for accessibility, not another walled garden.
Related MCP server: mcp-a11y-tools
audit_page ──► fix_contrast ──► generate_report ──► open_pr
(axe-core) simple_fixes (before/after) (controlled repo)
generate_alt_text
(the only LLM step)Detection is deterministic. Structural and contrast fixes are deterministic. A vision model is called only for alt text. Fixes are reinjected into the source by CSS selector (not by raw color value), so the patched file is what gets committed.
Tool | What it does | Deterministic? |
| Playwright + axe-core, returns structured WCAG violations (with selectors and colors) | Yes, no LLM |
| Closest WCAG-compliant foreground color (AA 4.5:1 normal text) | Yes, no LLM |
| Missing | Yes, no LLM |
| Vision model describes an image for an HTML | No, the only LLM step |
| Self-contained before/after HTML report | Yes, no LLM |
| Opens a mergeable PR via Octokit. Strict guardrail: only ever touches | Yes, no LLM |
Each tool's logic is isolated and testable off-MCP, with no shared state between tools. The deterministic helpers in src/lib are pure (no I/O); audit_page, generate_alt_text, and open_pr perform I/O (browser, model, GitHub) by nature.
TypeScript end-to-end, ESM, Node 22+. MCP TypeScript SDK 1.x, Playwright + axe-core, Octokit, Anthropic SDK, Zod v3.
pnpm install
pnpm exec playwright install chromium
cp .env.example .env # fill in keys (see Configuration)Run the MCP server (stdio):
pnpm devInspect it with the MCP Inspector:
pnpm inspectRun the full demo loop (audit, fix, report) on the bundled broken page:
pnpm exec tsx src/runner/demo.ts demo-site/index.html --report a11y-report.html
# add --alt to also generate alt text (needs ANTHROPIC_API_KEY)
# add --pr to open a PR on A11Y_TARGET_REPO (needs GITHUB_TOKEN)For the coherent loop, remediate the file that actually lives in the target repo and re-PR the same path:
pnpm exec tsx src/runner/demo.ts --from-repo index.html --alt --pr--from-repo <path> fetches that file from A11Y_TARGET_REPO, audits and fixes it, then opens a PR editing the same path (no demo gap: you fix the exact file the repo serves). Scratch files are written to the OS temp dir and removed on exit; only the report stays in the working directory.
Runner options:
Flag | Effect |
| Local HTML source (default |
| Fetch and remediate this path from |
| Also run |
| CSS selector for the image to describe (default: images flagged by the audit). |
| Open a PR on |
| Path of the file inside the target repo (defaults to |
| Where to write the HTML report (default |
Copy .env.example to .env:
ANTHROPIC_API_KEY=... # used ONLY by generate_alt_text
GITHUB_TOKEN=... # used ONLY by open_pr
A11Y_TARGET_REPO=owner/repo # STRICT guardrail: the only repo open_pr will touch
A11Y_ALT_TEXT_MODEL=claude-haiku-4-5 # optional, defaults to HaikuThe server boots even without keys. Only the tool that needs a key fails, with a clear message.
Add this to your Claude Desktop MCP config (claude_desktop_config.json):
{
"mcpServers": {
"mcp-a11y": {
"command": "pnpm",
"args": ["--dir", "/absolute/path/to/mcp-a11y", "dev"]
}
}
}Then ask Claude to audit a URL, fix the issues, and open a PR.
demo-site/index.html is an intentionally broken page (images without alt, poor contrast, no lang, form without labels). It is 100% static with zero JavaScript, so the rendered DOM equals the source file, and all colors live in a single <style> block. That invariant is what makes deterministic reinjection of fixes into the source reliable.
For a coherent audit-to-PR loop, run the runner with --from-repo <path>: it fetches that file from A11Y_TARGET_REPO, audits and fixes it, and re-PRs the same path. Relative image URLs are resolved over the raw repo URL so alt text works on a locally audited copy. You fix the exact file the repo serves, with no demo gap.
open_pr never accepts an arbitrary repo. The target comes only from A11Y_TARGET_REPO, validated as exactly owner/repo. Passing a different repo is refused before any network call. This is a controlled demo target by design.
pnpm test # node:test via tsx
pnpm typecheck # tsc on src and testThe deterministic core (contrast math) is unit tested, and the full remediation loop has an end-to-end test (audit, fix, reinject, re-audit clears the violations).
Audit a web page against WCAG rules with axe-core (Playwright headless Chromium). 100% deterministic detection - no LLM. Returns structured violations with selectors and colors.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to audit. http(s):// (public target) or file:// (local mirror). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behaviors: it is deterministic (no LLM), uses axe-core via Playwright headless Chromium, and returns structured violations with selectors and colors. However, it misses details like prerequisites for URL accessibility or potential limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two dense sentences with no filler. The first sentence states primary action and method; the second describes deterministic nature and output format. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter fully described in schema, no output schema, and no annotations, the description provides sufficient information about behavior, output format, and deterministic nature. It covers all critical aspects an agent needs to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context to the 'url' parameter by specifying allowed formats (http(s):// or file://) and scope (public target or local mirror). This adds value beyond the schema's basic description, but the parameter is straightforward.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits a web page against WCAG rules using axe-core, is deterministic, and returns structured violations. It distinguishes itself from sibling tools like fix_contrast (which fixes issues) and generate_alt_text (which generates alt text), making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for auditing before fixing, but does not explicitly state when to use this tool versus alternatives like simple_fixes or generate_report. No 'when not to use' guidance is provided, limiting its helpfulness for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the closest WCAG-compliant foreground color for a fg/bg pair (AA 4.5:1 normal text). Deterministic - no LLM.
| Name | Required | Description | Default |
|---|---|---|---|
| bg | Yes | Background color: #rgb, #rrggbb or rgb(r,g,b) | |
| fg | Yes | Foreground color: #rgb, #rrggbb or rgb(r,g,b) | |
| target | No | Target contrast ratio (default 4.5, AA normal text) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explicitly states 'Deterministic - no LLM', adding behavioral confidence. However, it does not specify what the output format is or whether it mutates anything.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with key information front-loaded. Every word serves a purpose: verb, resource, constraints, determinism.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify return value. It states it computes a color but not what the tool returns (just the new color? a ratio? success status?). Also missing error handling info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes parameters with formats and default. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (compute) and resource (foreground color) with clear context (WCAG-compliant, AA 4.5:1 normal text). It distinguishes from siblings like audit_page and generate_alt_text by focusing on color computation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is clear (when you need WCAG-compliant foreground color), but no explicit guidance on when not to use or alternatives among siblings. The description does not exclude any context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe an image for an HTML alt attribute using a vision model. The ONLY LLM-backed tool. Provide either imageUrl, or selector + pageUrl to locate an on a page.
| Name | Required | Description | Default |
|---|---|---|---|
| pageUrl | No | Page URL to load when using `selector` to locate the image. | |
| imageUrl | No | Direct http(s):// URL of the image. For local images, use selector + pageUrl. | |
| selector | No | CSS selector of an <img> on `pageUrl` (alternative to imageUrl). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool uses a vision model and is LLM-backed, but lacks details on error handling, permissions, limitations (e.g., image size, accessibility), or what happens if both params are provided. Some behavioral context is added, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose, the second provides usage instructions. It is front-loaded, efficient, and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core purpose and parameter usage, but lacks mention of the return value (alt text string) and error scenarios. Given no output schema and no annotations, some additional context about what the tool returns would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two mutually exclusive usage patterns (imageUrl vs. selector+pageUrl) and notes that local images require the selector+pageUrl approach. This clarifies when to use each parameter beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Describe an image for an HTML alt attribute using a vision model.' It also distinguishes itself from siblings by claiming to be 'The ONLY LLM-backed tool.' This provides a specific verb-resource combination and differentiates it from other tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Provide either imageUrl, or selector + pageUrl to locate an <img> on a page.' It explains two usage modes but does not explicitly mention when not to use the tool or reference alternative tools beyond the uniqueness claim.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a self-contained before/after HTML accessibility report from an audit and applied fixes. No LLM. Returns the HTML string.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Audited URL / page label shown in the report header. | |
| altTexts | No | Generated alt texts (target/altText/model). | |
| auditAfter | No | AuditResult after fixes (after column). | |
| auditBefore | Yes | AuditResult from audit_page (before fixes). | |
| generatedAt | No | Optional timestamp shown in the header. | |
| simpleFixes | No | AppliedFix[] from simple_fixes. | |
| contrastFixes | No | ContrastReinjection[] from the contrast glue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry all behavioral transparency. It mentions 'No LLM' (rule-based) and returns HTML string, but lacks details on side effects, performance, or size limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose, no fluff. Each sentence adds unique information (purpose, behavior, output format).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and nested objects, the description covers the high-level purpose but does not clarify behavior when optional parameters (like auditAfter) are missing, which is important for a report generator.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context by indicating the report compares 'before/after' and uses fixes, linking parameters like auditBefore and simpleFixes together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Build' and the resource 'self-contained before/after HTML accessibility report', distinguishing it from sibling tools like audit_page or fix_contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after audits and fixes but does not explicitly state when to use or not use this tool versus alternatives, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a mergeable PR with the remediated files. STRICT GUARDRAIL: only ever operates on the repo configured in A11Y_TARGET_REPO - never an arbitrary repo.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Pull request body. | |
| repo | No | Optional safety assertion - must equal A11Y_TARGET_REPO if set. | |
| files | Yes | Files to commit on the new branch. | |
| title | Yes | Pull request title. | |
| branch | Yes | New branch name to create for the PR. | |
| commitMessage | No | Commit message (defaults to the PR title). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions the repo constraint and that the PR is 'mergeable'. It does not disclose failure modes, auth requirements, or behavior on existing branches, which is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence plus guardrail) and front-loaded with the main action. Every part earns its place without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (3 required) and no output schema, the description is too minimal. It doesn't explain the process of creating a branch, committing files, or what 'remediated files' implies. An agent would need more context to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented in the schema. The description adds no extra semantics about parameters, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool opens a mergeable PR with remediated files, and includes a guardrail about the target repo. However, it does not explicitly distinguish itself from sibling tools, though its unique purpose is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The STRICT GUARDRAIL provides a specific usage rule (only operates on A11Y_TARGET_REPO). But no explicit when-to-use or when-not-to-use guidance is given, nor are alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check. Returns 'pong', optionally echoing a message.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional message echoed back in the pong |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly discloses the return value ('pong') and the effect of the optional message parameter (echoed back). It does not mention potential errors or side effects, but for a simple health check this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences that convey essential information without redundancy or filler. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full schema coverage, and no output schema, the description covers all essential aspects: purpose, behavior, and parameter effect. It is complete for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'message' parameter well. The tool description reinforces that the message is echoed, but adds little new semantics beyond the schema. Baseline 3 is appropriate due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as a health check returning 'pong', which is a specific verb and resource. It is distinct from all sibling tools (audit_page, fix_contrast, etc.) which involve more complex actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for health checking but does not explicitly state when to use it versus alternatives. Given the simplicity, implied usage is acceptable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply deterministic structural fixes to HTML: missing lang, missing title, unlabeled form controls. Returns the patched HTML and the list of fixes. No LLM.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | HTML source to remediate | |
| lang | No | Language code for <html lang="…"> (default "en") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states 'No LLM' and returns patched HTML and fix list, but does not mention if the input is modified in-place, permissions needed, error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded. First sentence states purpose and scope, second sentence clarifies return and deterministic nature. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 2 parameters and no output schema, the description adequately covers purpose, fix types, and return value. Missing edge case handling or validation info, but sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description links the 'lang' parameter to fixing missing lang attribute, adding slight value beyond schema. No further semantics added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies deterministic structural fixes to HTML, specifically targeting missing lang, missing title, and unlabeled form controls. It distinguishes from siblings by emphasizing deterministic, non-LLM fixes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or avoid this tool versus alternatives like audit_page or fix_contrast. It does not mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: audit_page does WCAG auditing, fix_contrast computes contrast fixes, generate_alt_text generates alt text, generate_report builds reports, open_pr opens PRs, ping is health check, and simple_fixes applies structural fixes. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (e.g., audit_page, fix_contrast, generate_alt_text, simple_fixes). Even ping fits the pattern of a simple verb. Snake_case is used uniformly.
With 7 tools, the server is well-scoped for accessibility tasks. Each tool covers a key aspect of auditing, fixing, reporting, and deployment, without being overwhelming or sparse.
The tool surface covers the full lifecycle: audit (audit_page), fix contrast (fix_contrast), generate alt text (generate_alt_text), apply structural fixes (simple_fixes), generate report (generate_report), and deploy changes (open_pr). No obvious gaps for the domain.
Scan URLs for WCAG 2.1 violations, generate AI fixes, and produce VPAT 2.5 compliance reports.
Website QA for your coding agent: audit SEO, performance, security, accessibility over MCP.
Pilot AEO/GEO from Claude: bulk audits, server-side fixes via WordPress plugin, AI citations.
Scan a web page for accessibility, security, privacy, quality and SEO issues, with fixes.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/P4ST4S/mcp-a11y'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
