# Unofficial MCP Server for USWDS

> Unofficial MCP Server for USWDS is an open-source MCP server for developer tools. Official USWDS markup, class-aware validator and page composer for AI-built UI. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/bibekpdl/uswds-mcp
- **MCP Registry name:** io.github.bibekpdl/uswds-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [design and media](https://ai-powered.com/categories/design-and-media)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add uswds-mcp -- npx -y uswds-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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

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

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/unofficial-mcp-server-for-uswds
