# Unofficial MCP Server for USWDS [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/bibekpdl/uswds-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/unofficial-mcp-server-for-uswds

## Description
Unofficial USWDS MCP: official markup, class-aware validator, and page composer for AI tools.

## Tools
Capabilities this server exposes over MCP:

- **get_component_markup** — Official HTML** for a component/page template and its variants (`accordion`, `footer` + `slim`, `sign-in`, ...). Understands everyday names (`dropdown` → select).
- **compose_uswds_page** — Build a full page from structured sections: hero, content, alert, summary box, cards, process list, step indicator, accordion, table, form, contact.
- **validate_uswds_markup** — Validate fragments or full pages: real class names, component structure, forms, ARIA, accessibility basics.
- **find_uswds_classes** — Look up real classes, including utilities and responsive variants (`margin top 2`, `tablet grid col 6`).
- **generate_uswds_page** — Quick start from free-text requirements; returns an editable section spec, bracketed placeholders, and its own validation.
- **recommend_uswds_structure** — USWDS-first structure for a service or page.
- **search_uswds** — Search docs, accessibility and usage guidance (with synonym expansion).
- **get_component** — Structured guidance, plus the canonical markup for components.
- **get_uswds_integration_recipe** — Framework setup for Next.js, Vite/React, static HTML, Rails, Drupal.
- **validate_uswds_project_setup** — Catch wrong CSS import paths, missing scripts, CDN use, copied `dist`, global CSS risk.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "unofficial-mcp-server-for-uswds": {
    "command": "npx",
    "args": ["-y","uswds-mcp"]
  }
}
```

## Documentation

## 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:

```sh
npx -y uswds-mcp
```

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

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/unofficial-mcp-server-for-uswds/readme_