Skip to content
MCP server

handmade

Design brief, token system and pass/fail check so AI-built UIs avoid generated looks

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI
Runs
Locally
Version
0.3.2
Listing updated
today

Similar MCP servers

About handmade

handmade is an open-source MCP server for design and media. It runs locally on your machine and is started by your AI client.

Handmade works in three stages around a model that builds interfaces. Before generation it asks only about facts missing from your request, such as audience, best sellers or opening hours, and writes a design brief plus a token file, handmade.system.json. During generation it injects typographic scales, palettes and layout constraints into the model's context. Afterwards handmade check audits source files, and optionally computed styles in a headless browser, and fails code that drifts from the tokens.

The README's example builds one landing page twice: the plain request scored 15/100 and failed on things like Inter as the only typeface, purple gradients, three equal feature cards and invented stats, while the same request through handmade scored 100/100. Facts the user skipped are listed under "Facts still missing" so the model leaves marked slots instead of inventing testimonials or hours.

It installs from PyPI with pipx or uvx, runs offline with no API keys and no runtime dependencies, and the MCP server is a second command, handmade-mcp.

Install

Run in a terminal

claude mcp add handmade -- uvx handmade

Add to claude_desktop_config.json

{
  "mcpServers": {
    "handmade": {
      "command": "uvx",
      "args": [
        "handmade"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "handmade": {
      "command": "uvx",
      "args": [
        "handmade"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "handmade": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "handmade"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "handmade": {
      "command": "uvx",
      "args": [
        "handmade"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "handmade": {
      "command": "uvx",
      "args": [
        "handmade"
      ]
    }
  }
}

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

What it does

Brief synthesis
Asks targeted questions for missing facts and emits a design brief and token schema.
Generation guidance
Feeds type scales, palettes and layout rules into the model's context.
Pass/fail check
handmade check scores source files and fails drift from the tokens.
Rendered mode
Optional Playwright run audits computed styles, fonts and contrast.
Fix prompts
handmade fix builds a refactoring prompt from an existing codebase.
CI support
The README describes a GitHub Actions setup.
Offline use
Runs locally with no API keys or runtime dependencies.

Good for

  • Brief an AI to build a landing page for a small business without invented facts
  • Audit an AI-generated site for common generated-design tells
  • Fail a build when styles drift outside the token file
  • Generate a refactor prompt for an existing front end
  • Add a design gate to a pull request pipeline

Pricing

Open source

Free; installed from PyPI

handmade FAQ

How do I add it to Claude Code?

Run claude mcp add handmade -- uvx --from handmade handmade-mcp.

Does it call an LLM or need keys?

No. The README says it runs entirely offline with no API keys.

What does rendered mode need?

The optional render extra and Playwright with Chromium.

What Python version is required?

Python 3.10 or newer.

Is handmade free?

Yes. handmade is open source, so you can use and self-host it for free.

How do I add handmade to Claude Code?

Run this command in your terminal: claude mcp add handmade -- uvx handmade

What are the best alternatives to handmade?

The closest alternatives to handmade 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