Skip to content
MCP server

Unofficial MCP Server for USWDS

Official USWDS markup, class-aware validator and page composer for AI-built UI

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.2.1
Listing updated
today

Similar MCP servers

About Unofficial MCP Server for USWDS

Unofficial MCP Server for USWDS is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

This unofficial server targets a specific failure: language models write U.S. Web Design System code from memory, inventing classes like usa-btn, omitting the overlay a mobile menu needs or putting a card without its container. It supplies markup rendered from the official @uswds/uswds templates, described as 178 snippets covering about 70 components and page templates.

Its validator rejects any usa-* class not in the stylesheet and suggests the likely one, and also checks required children, ARIA wiring, form structure, heading order, duplicate ids and link and button names. Findings include the element, a suggested fix and a docs link so the model can repair its own output. A composer builds pages from structured sections, and project-setup checks catch wrong CSS import paths or CDN use.

It is independent and not affiliated with GSA or the USWDS team. It runs over stdio with npx, needs no network or API key, and all tools are read-only.

Install

Run in a terminal

claude mcp add uswds-mcp -- npx -y uswds-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "uswds-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "uswds-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "uswds-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "uswds-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "uswds-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "uswds-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (12)

Taken from the project documentation; the running server may differ.

get_component_markup
Official HTML for a component or page template
compose_uswds_page
Builds a page from structured sections
validate_uswds_markup
Validates USWDS markup
find_uswds_classes
Looks up real USWDS classes
generate_uswds_page
Quick-start page from free-text requirements
recommend_uswds_structure
Recommends a USWDS structure
search_uswds
Searches docs and guidance
get_component
Component guidance
get_pattern
Pattern guidance
get_template
Template guidance
get_uswds_integration_recipe
Framework setup recipe
validate_uswds_project_setup
Checks project setup

What it does

Official markup
Returns USWDS HTML for components and templates.
Class validator
Rejects invented usa-* classes with suggestions.
Page composer
Builds an accessible page from structured sections.
Class lookup
Finds real classes including utilities.
Integration recipes
Setup for Next.js, Vite/React, static HTML, Rails and Drupal.
Setup validation
Flags wrong CSS paths and missing scripts.

Good for

  • Build a government service page that follows USWDS
  • Validate AI-written markup
  • Add the USWDS header and footer correctly
  • Set up USWDS in a Next.js project

Pricing

Open source

Free and open source

Unofficial MCP Server for USWDS FAQ

Is it official?

No. It is unaffiliated with GSA, TTS or the USWDS team.

Does it need network or a key?

No. The data ships in the package.

Can it change files?

No. All tools are read-only.

Which frameworks have recipes?

Next.js, Vite/React, static HTML, Rails and Drupal.

Is Unofficial MCP Server for USWDS free?

Yes. Unofficial MCP Server for USWDS is open source, so you can use and self-host it for free.

How do I add Unofficial MCP Server for USWDS to Claude Code?

Run this command in your terminal: claude mcp add uswds-mcp -- npx -y uswds-mcp

What are the best alternatives to Unofficial MCP Server for USWDS?

The closest alternatives to Unofficial MCP Server for USWDS are REA, HyperFrames by HeyGen, Context7, Chrome DevTools MCP and Codebase Memory.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers