Pixl

Open-source MCP server for designing mobile UIs. Pixl plugs into whatever AI coding host you already use (Claude Code, Cursor, …) and turns it into a guided mobile-UI design tool. Your host's model does the generating — Pixl supplies the taste it lacks: a locked design-system token contract, a linter that rejects off-standard output, and a local browser preview with a phone-frame gallery and a draggable user-journey flow map. Everything runs locally.

Status: v0.1, feature-complete — MCP server, workspace, live preview, design-system presets + token contract, screen generation with the taste linter, and the draggable user-journey flow canvas.

How it fits together

host (Claude Code / Cursor) ──MCP stdio──▶ pixl-mcp (Node/TS)
                                             │  owns .pixl/ workspace, runs linter
                                             ▼
                            localhost:4321  Vite + React preview
                              ├── Screen gallery (phone frames, live-reload)
                              └── Flow canvas (dotted bg, draggable)

State lives in a .pixl/ folder in your project: tokens.json, design/*.md, screens/*.html, flow.json.

Install

Pixl auto-starts when your host connects: it creates the .pixl/ workspace, boots the preview, and opens localhost:4321 in your browser. No pixl_init call needed — just point your host at it and start asking for screens.

npx (recommended):

Cursor — ~/.cursor/mcp.json:

{ "mcpServers": { "pixl": { "command": "npx", "args": ["-y", "pixl-mcp"] } } }

Claude Code:

claude mcp add pixl -- npx -y pixl-mcp

Docker (no Node needed; fully isolated). -p 4321:4321 forwards the preview; the sh -c wrapper reaps any prior container so relaunches don't clash on the port:

{
  "mcpServers": {
    "pixl": {
      "command": "sh",
      "args": [
        "-c",
        "docker rm -f pixl-mcp >/dev/null 2>&1; exec docker run --rm -i --name pixl-mcp -p 4321:4321 -v \"$PWD\":/work -w /work pixl-mcp"
      ]
    }
  }
}

Build the image first with docker build -t pixl-mcp . (or pull it once published).

Develop

npm install --include=dev   # this machine has npm omit=dev set globally
npm run build               # compile the server to dist/
npm run typecheck
npx vitest run               # linter unit tests (pass/fail fixtures)
node scripts/smoke.mjs        # workspace + preview API end-to-end
node scripts/mcp-smoke.mjs    # drives the server as a real MCP client
node scripts/phase2-smoke.mjs # design system + screen plan
node scripts/phase3-smoke.mjs # write/lint screen: reject bad, accept fixed
node scripts/phase4-smoke.mjs # flow graph + drag-persist round-trip

Register a local build (from source)

Claude Code:

npm install --include=dev && npm run build
claude mcp add pixl -- node /absolute/path/to/pixl-mcp/dist/index.js

The preview auto-starts and opens localhost:4321 — then ask your assistant to set a design system and generate screens.

Tools

| Tool | Purpose | |---|---| | pixl_init | Re-open the preview / fetch its URL (auto-runs on startup — you don't call it) | | pixl_status | Report workspace state | | pixl_list_presets / pixl_set_design_system / pixl_plan_screens | Design system + screen plan | | pixl_write_screen / pixl_lint_screen | Generate + lint screens | | pixl_set_flow | User-journey flow graph |

MIT.