Unofficial MCP Server for USWDS

uswds-mcp

Make AI-generated government UI actually USWDS-compliant.

An MCP server that gives Claude, Cursor, Copilot, Windsurf and any other MCP client the official U.S. Web Design System markup, a validator that knows every real USWDS class, and a page composer that outputs accessible, validated pages.

Unofficial and independent. Not affiliated with, endorsed by, or maintained by GSA, TTS, or the official USWDS team. See NOTICE.md.

The problem

LLMs write USWDS from memory. They invent usa-btn, forget the usa-overlay that makes the mobile menu work, put usa-card markup without its container, and wire up accordions to nothing. The result looks plausible and is subtly broken.

uswds-mcp closes that loop:

recommend_uswds_structure  →  get_component_markup  →  compose_uswds_page  →  validate_uswds_markup
        (what to use)          (official HTML)         (accessible page)       (fix until 0 errors)

What a validator finding looks like

{
  "severity": "error",
  "rule": "unknown-class",
  "message": "\"usa-alrt\" is not a class defined by USWDS.",
  "selector": "div.usa-alrt",
  "snippet": "<div class=\"usa-alrt usa-alert--eror\">",
  "suggestion": "Did you mean \"usa-alert\"?"
}

Findings carry the offending element, a fix suggestion, the component to look up, and a docs link, so the model can repair its own output.

Quick start

npx -y uswds-mcp

Add it to your MCP client:

{
  "mcpServers": {
    "uswds": { "command": "npx", "args": ["-y", "uswds-mcp"] }
  }
}

Claude Code: claude mcp add uswds -- npx -y uswds-mcp

Setup for Claude Desktop, Cursor, VS Code, Windsurf and others: docs/CLIENTS.md. Ready-made configs are in examples/.

No network, API key, or ingest step needed: the data ships in the package.

Tools

All tools are read-only. See docs/TOOLS.md for arguments and recommended sequences.

Shortened. The full README is on GitHub.