Unofficial MCP Server for USWDS

What Unofficial MCP Server for USWDS MCP server does

Unofficial MCP Server for USWDS MCP server gives AI clients a local MCP interface to USWDS component markup, page patterns, templates, class names, and documentation. It is intended for developers building government or public-service interfaces with the U.S. Web Design System and wanting generated output checked against known USWDS structure.

The server can return canonical HTML for components and page templates, including variants and common-name aliases. It can also assemble complete pages from structured sections such as alerts, cards, forms, tables, accordions, process lists, contact blocks, and hero content. Free-text page requirements can be converted into an editable section specification with placeholders and validation results.

How it works

The package includes data derived from USWDS templates, fixtures, stylesheets, and documentation. Its current data targets USWDS 3.14.0. Because the data is bundled, normal use does not require an API key, network access, or a separate ingestion step.

A typical workflow starts by asking for a recommended structure, retrieves canonical markup for selected components, composes the page, and then validates the result. Validation checks known USWDS classes, component relationships, forms, ARIA wiring, headings, identifiers, links, images, buttons, scripts, and basic accessibility conditions. Findings identify the affected element and can include a suggested correction, component reference, and documentation link.

Setup and configuration

Run the server with:

npx -y uswds-mcp

An MCP client can launch it as a standard stdio server:

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

Claude Code can use claude mcp add uswds -- npx -y uswds-mcp. The repository also provides client setup documentation and example configurations. No environment variables are required by the documented quick-start configuration.

Tools and capabilities

Unofficial MCP Server for USWDS MCP server exposes read-only tools, including:

• get_component_markup for official component or page-template HTML and variants.
• compose_uswds_page for building a page from named structured sections.
• validate_uswds_markup for checking fragments or complete pages.
• find_uswds_classes for locating component, utility, and responsive classes.
• generate_uswds_page for turning free-text requirements into an editable page specification.
• recommend_uswds_structure for proposing a USWDS-oriented service or page structure.
• search_uswds for documentation, accessibility, and usage guidance.
• get_component for structured component guidance and canonical markup.
• get_uswds_integration_recipe for Next.js, Vite/React, static HTML, Rails, and Drupal setup guidance.
• validate_uswds_project_setup for detecting common CSS, script, CDN, distribution-copy, and global-CSS issues.

The package also exposes USWDS resources for components, patterns, templates, tokens, and package data, plus prompts for tasks such as auditing, conversion, and project integration.

Limitations and notes

The Unofficial MCP Server for USWDS MCP server performs static analysis. It cannot determine rendered color contrast, visual reading order, actual screen-reader behavior, or full Section 508 conformance. Generated pages still require testing with tools such as axe, keyboard navigation, and screen readers.

Custom classes that do not use the usa- prefix are not validated. Placeholder text from upstream fixtures may remain in returned markup. The project is unofficial and is not affiliated with, endorsed by, or maintained by GSA, TTS, or the official USWDS team.