# handmade

> handmade is an open-source MCP server for design and media. Design brief, token system and pass/fail check so AI-built UIs avoid generated looks. It runs locally on your machine and is started by your AI client.

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

## About

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

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add handmade -- uvx handmade
```

### Claude Desktop (claude_desktop_config.json)

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

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

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

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

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

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

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

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

```json
{
  "mcpServers": {
    "handmade": {
      "command": "uvx",
      "args": [
        "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.

## 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/handmade
