@just-every/12ui

MCP (Model Context Protocol) stdio server that proxies the 12ui API (default: https://12ui.com) so MCP clients can create, sync, and check design runs.

Quick start

The recommended path is to run the guided installer once. It will:

• Authenticate you (if needed)
• Install a local 12ui launcher (no npx required after)
• Configure detected MCP clients (and install Skills where supported)

npx -y @just-every/12ui@latest install

After install, you can use 12ui directly.

Authenticate

Login once (interactive approval-link flow):

12ui auth login

If you do not have 12ui on PATH yet, you can always run:

npx -y @just-every/12ui@latest auth login

If your user belongs to multiple organizations, this will prompt you to pick one. To skip the prompt, pass --account <slug>.

Run as an MCP server (stdio)

12ui

Fallback (no local install):

npx -y @just-every/12ui@latest

Install into common MCP clients

This writes MCP server config entries for detected clients (Claude Desktop, Cursor, Gemini CLI, Qwen Code, Codex, and Every Code), and installs a small local playbook “skill” where supported.

npx -y @just-every/12ui@latest install

By default, install will prefer a local launcher and attempt to ensure ~/.local/bin is on your PATH. To skip modifying shell config files:

npx -y @just-every/12ui@latest install --no-path

To force-install into all supported clients:

npx -y @just-every/12ui@latest install --client all --yes

Non-interactive (skip auth login, leave existing auth untouched):

npx -y @just-every/12ui@latest install --client all --yes --skip-auth

To remove the MCP server + playbook skill from detected clients:

npx -y @just-every/12ui@latest remove

Claude Desktop config example

{
  "mcpServers": {
    "12ui": {
      "command": "/absolute/path/to/12ui",
      "args": []
    }
  }
}

Tip: GUI apps may not inherit your shell PATH, so an absolute path is recommended.

Authentication (recommended)

This package uses the JustEvery login approval-link flow:

• It creates an approval request via POST /api/auth/m2m/approval-requests.
• You click a single approval URL in your browser.
• The CLI polls, receives a short-lived bearer token, then exchanges it for a Better Auth session token via POST /api/auth/m2m/session.
• The session token is stored locally and used as better-auth.session_token for API calls.

This avoids needing long-lived client secrets and is the lowest-friction path for humans.

Configuration

Config file

• Default path: $XDG_CONFIG_HOME/just-every/12ui/mcp.json (or ~/.config/just-every/12ui/mcp.json)
• Override: DESIGN_MCP_CONFIG_PATH=/path/to/mcp.json

Environment variables

• DESIGN_MCP_ORIGIN (default: https://12ui.com)
• LOGIN_ORIGIN (default: https://login.justevery.com)
• DESIGN_MCP_SESSION_TOKEN (bypass config)
• DESIGN_MCP_ACCOUNT_SLUG (optional; otherwise chosen from /api/accounts)

MCP tools

CLIs MUST follow this order when creating a user interface or visual element: design.create → design.sync → design.check.

Available tools:

• design.create — Create a new design. Returns run id.
• design.sync — Wait for completion, extract assets, and sync to a folder (can take up to 30 mins).
• design.check — Capture a screenshot and return guidance; accepts URL or local HTML file path.
• design.instructions — Return the required workflow instructions for CLIs.