Unofficial MCP Server for USWDS
Official USWDS markup, class-aware validator and page composer for AI-built UI
- 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-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"uswds-mcp": {
"command": "npx",
"args": [
"-y",
"uswds-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"uswds-mcp": {
"command": "npx",
"args": [
"-y",
"uswds-mcp"
]
}
}
}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.


