Pixl is an MCP server that turns AI coding hosts into a guided mobile UI design tool, enforcing a locked design-system token contract and providing a local browser preview with a phone-frame screen gallery and draggable user-journey flow map.
Initialize the workspace: Set up the .pixl/ folder, boot the local browser preview at localhost:4321, and optionally open it automatically in your browser.
Check workspace status: Get a snapshot of the current state — initialization status, active design system, screen count, flow node count, and preview URL.
Browse and set a design system: List curated design-system presets, then select one (with optional overrides) or provide fully custom tokens (colors, typography, spacing, radius, shadows, breakpoints). This locks a token contract that all screens must follow.
Plan screens and user journey: Define an ordered list of screens (IDs, names, descriptions) and directed transitions between them, seeding both the screen plan and the flow map.
Generate and save screens: Submit full self-contained HTML for a screen; it is linted against the token contract — valid screens are saved and live-rendered in the gallery, invalid ones return specific violation feedback.
Lint screens without saving: Validate a screen's HTML against the token contract as a dry run, to catch violations before committing.
Update the flow canvas: Define or update the user-journey graph (nodes and directed edges with transition labels) rendered on the draggable flow canvas, preserving manually set node positions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pixl start a new mobile UI design project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: CodeCrafted Design MCP
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-mcpDocker (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).
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-tripClaude Code:
npm install --include=dev && npm run build
claude mcp add pixl -- node /absolute/path/to/pixl-mcp/dist/index.jsThe preview auto-starts and opens localhost:4321 — then ask your assistant to set a design system and generate screens.
Tool | Purpose |
| Re-open the preview / fetch its URL (auto-runs on startup — you don't call it) |
| Report workspace state |
| Design system + screen plan |
| Generate + lint screens |
| User-journey flow graph |
MIT.
Create the .pixl workspace in the current project, boot the local browser preview, and open it. Call this first. Returns the preview URL to relay to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| openBrowser | No | Open the preview in the default browser automatically. |
Lint provided HTML against the active token contract WITHOUT saving. Use to check a draft before committing it with pixl_write_screen.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | Full screen HTML to lint. |
List the curated design-system presets. Show these to the user and let them pick one (by id) before calling pixl_set_design_system.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Record the screen list and the user journey between them. Writes screens.md and seeds the flow map. Do this after the design system is set and before generating screens.
| Name | Required | Description | Default |
|---|---|---|---|
| journey | No | Directed transitions between screen ids. | |
| screens | Yes | Ordered list of screens. |
Lock the design system. Pass a presetId (from pixl_list_presets) with optional overrides, OR fully custom tokens. Writes tokens.json + design/*.md and returns the TOKEN CONTRACT — obey it for every screen you generate.
| Name | Required | Description | Default |
|---|---|---|---|
| presetId | No | Preset id, e.g. 'clean-saas'. Omit only if passing customTokens. | |
| overrides | No | ||
| customTokens | No | Full custom token set (same shape as a preset's tokens). Use for a bespoke system. |
Set/update the user-journey graph the flow canvas renders. Provide the edges (transitions between screen ids). Nodes default to one per planned screen and keep any positions the user has dragged. Writes flow.json and live-updates the Flow tab.
| Name | Required | Description | Default |
|---|---|---|---|
| edges | Yes | Directed transitions between screens. | |
| nodes | No | Optional explicit node set/positions; omit to use one node per screen. |
Report current workspace state: whether initialized, the active design system, screen count, flow node count, and preview URL.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Submit a screen's HTML. It is linted against the token contract; on pass it is saved to screens/.html and live-renders in the gallery, on fail the violations are returned and NOTHING is saved — fix them and resubmit.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Screen id; matches a screen from pixl_plan_screens. | |
| html | Yes | Full self-contained HTML document for the screen, sized to the viewport and using the contract's headBlock + role classes. | |
| name | Yes | Human-readable screen name. | |
| description | No |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0pixl_initpixl_lint_screenpixl_list_presetspixl_plan_screenspixl_set_design_systempixl_set_flowpixl_statuspixl_write_screenScored across 8 tools
Each tool has a unique, clearly defined purpose (init, lint, list presets, plan screens, set design system, set flow, status, write screen) with no overlap or ambiguity.
All tools follow a consistent 'pixl_verb_noun' pattern in snake_case, making the naming predictable and understandable.
8 tools is well within the optimal range for a specialized server covering initialization, design system, planning, linting, and writing screens.
The tool set covers the core workflow end-to-end, though there is no explicit tool to list or delete screens (pixl_status only reports count). This minor gap does not significantly hinder usability.
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
Design your mobile app UI with AI, then have your coding agent build the real app from it.
A design agent in your coding agent's loop: briefs each screen, reviews UX and visual quality.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
