Mockups MPC

A self-hosted MCP server and gallery for AI-generated mockups. AI tools send mockups via MCP tool calls, the server stores and catalogs them, and you browse everything in a clean web gallery.

Token-efficient by design. MCP tool parameters flow through the model context, so sending a large HTML file via a tool call wastes tokens. Mockups MPC provides an HTTP upload endpoint (POST /api/upload) — the AI writes the file locally and curls it to the server, keeping file content entirely out of the model context. MCP tools handle lightweight operations only: listing, metadata, tagging, and deletion.

Prerequisites

• Docker (for deployment) or Python 3.12+ (for local development)
• An MCP-compatible AI client (Claude Code, Claude Desktop, etc.)
• Optional: Traefik reverse proxy (for production with TLS)

Why

Every time an AI tool generates a mockup, there's no consistent place for it to go. Files get scattered, sessions lose context, and there's no history. Mockups MPC solves this: the AI sends the mockup to the server, you view it in the gallery, and the local file gets cleaned up. One place for everything.

Architecture

┌─────────────────┐     MCP (HTTP/SSE)     ┌──────────────────────┐
│  Claude Code /  │ ◄───────────────────── │                      │
│  Claude Desktop │  send/list/get/update  │    Mockups MPC       │
│  Any MCP Client │  delete/tag            │    (FastAPI)         │
└─────────────────┘                        │                      │
                                           │  ┌────────────────┐  │
       Browser                             │  │  MCP Server    │  │
    ┌──────────┐      GET /                │  │  (fastmcp)     │  │
    │ Gallery  │ ◄──────────────────────── │  └────────────────┘  │
    │ Viewer   │                           │  ┌────────────────┐  │
    └──────────┘                           │  │  JSON API      │  │
                                           │  │  /api/*        │  │
                                           │  └────────────────┘  │
                                           │  ┌────────────────┐  │
                                           │  │  SQLite (WAL)  │  │
                                           │  │  + Filesystem   │  │
                                           │  └────────────────┘  │
                                           └──────────────────────┘

Single Docker container running a FastAPI app that serves two roles:

1. MCP Server — mounted at /mcp/ (HTTP transport) and /mcp/sse (SSE transport). AI tools connect here to send and manage mockups.
2. Web Gallery — served at /. Sidebar with project list and chronological feed, main viewer with iframe/image display.

Data Layer

• SQLite in WAL mode — metadata catalog (project, title, description, tags, content type, timestamps)
• Filesystem — mockup files stored in data/{project_slug}/{uuid}.{ext}
• Storage is a bind-mounted data/ directory next to the compose file

Tech Stack

• Python 3.12
• FastAPI + uvicorn
• fastmcp v3.x (standalone)
• SQLite via aiosqlite
• Jinja2 templates + vanilla JS
• Docker + Traefik

Security

There is no built-in authentication. All API endpoints and MCP tools are open to anyone who can reach the server. This is designed for trusted networks (LAN, VPN, Tailscale) or behind a reverse proxy that handles auth. If you deploy this on a public network, add authentication at the proxy layer.

MCP Tools

... View full README on GitHub