claude.design-mcp

An MCP that drives the real Claude Design web app from your editor/agent — log in once, then create, iterate on, and pull designs that claude.ai/design generates on your own account (not a local imitation).

How it works

• It drives your own logged-in Chrome (a dedicated profile) over CDP with playwright-core, and talks to the real claude.ai/design "Omelette" API as you, through your browser session.

• Generation is triggered the way the website does it — your prompt is typed into the design composer and submitted; the tool then waits for the turn to finish (the ReleaseTurn network signal + file-tree stability) and reports the files Claude Design wrote. Files are pulled back to local on request.

• Project metadata, files, deletes, and direct file edits use the documented JSON RPCs (CreateProject / ListFiles / GetFile / EditFile / DeleteProject), run in-page so they share your session + Cloudflare clearance.

• Not a claude -p mimic. Every design is produced by claude.ai/design itself.

Related MCP server: Browser Agent MCP

Tools

Setup

npm install                  # installs playwright-core (NO browser download — uses your Chrome)
node src/server.mjs login    # opens Chrome once; log into claude.ai (session is then reused, invisibly)

Register as a local MCP (opencode example):

{ "mcp": { "claude-design": { "type": "local", "command": ["node", "/abs/path/claude.design-mcp/src/server.mjs"], "enabled": true } } }

CLI

node src/server.mjs login
node src/server.mjs list
node src/server.mjs list-systems
node src/server.mjs create "minimal landing page for a coffee shop" coffee --model opus
node src/server.mjs create "simple pricing card" pricing --design-system "Frontend Design System"
node src/server.mjs iterate <projectId> "add a dark mode toggle to the header" --model sonnet
node src/server.mjs check <projectId>
node src/server.mjs pull <projectId|name>
node src/server.mjs preview <projectId|name> [outDir] [width]
node src/server.mjs delete <projectId>
node src/server.mjs sync <packageDir> [--timeout-ms 900000]

After the one-time login, list/create/iterate/pull run with no visible window (off-screen Chrome) and reuse the persisted session.

Generation options

• design_create, design_iterate, and design_variants accept an optional model. Use a family (opus, sonnet, haiku, or fable) to select that family's newest version from the live claude.ai/design menu. Pin a version with forms such as opus-4.8, opus-5, opus 5.0, claude-opus-4-8, or anthropic/claude-opus-5. New family versions become available automatically when they appear in the site menu. If a requested version is unavailable, the error lists the live menu options. For CLI create and iterate, pass the same value to --model.

• design_create, design_iterate, and design_variants accept an optional designSystem (CLI --design-system), the name of one of the account design systems reported by design_system_list. It is matched case-insensitively, an unambiguous partial name works, and an unknown name errors with the list the composer offers. The chosen system replaces the org default rather than adding to it, and the result echoes the resolved name. claude.ai only offers the picker while a project has produced no design yet, so designSystem belongs on design_create; on design_iterate it works only for such a project and otherwise errors instead of silently ignoring the request. design_variants grounds every variant in the same system.

• design_create and design_iterate accept wait (default true). Set wait: false to return immediately after submission with { submitted: true, pending: true }; the CLI equivalent is --no-wait.

• design_create with an explicit name is find-or-create: an existing project with that exact name is reused (newest wins on collisions) and the result carries reused: true, so repeated calls iterate one project instead of piling up duplicates. Pass fresh: true to force a new project. Without name (prompt-derived name), every call creates a new project as before.

• Poll submitted work with design_check({ projectId }), or node src/server.mjs check <projectId>. Its status is generating, awaiting_input, done, or no_output.

Asynchronous workflow

# 1. Submit without waiting
node src/server.mjs create "카드 UI" my-card --no-wait --model opus
# → { projectId: "...", submitted: true, pending: true }

# 2. Continue with other work...

# 3. Poll for completion (every 2-5 minutes is recommended)
node src/server.mjs check <projectId>
# → { status: "done", files: [...] }

# 4. Pull and preview the finished design
node src/server.mjs pull <projectId>
node src/server.mjs preview <projectId>

Requirements

• Node.js 22+ (uses built-in fetch/WebSocket; playwright-core is the only npm dependency)

• Google Chrome (the tools drive a dedicated Chrome profile)

• A claude.ai account with Design access (you log in once via design_login)

Env

• CLAUDE_DESIGN_PROFILE — dedicated Chrome profile dir (default ~/.cache/claude-design-mcp/chrome-profile)

• CLAUDE_DESIGN_CHROME — path to Google Chrome (default: macOS Google Chrome)

• CLAUDE_DESIGN_CDP_PORT — remote-debugging port (default 9377)

• CLAUDE_DESIGN_DIR — where design_pull / design_preview write, each into its own <project>/ folder (default: the working folder); an explicit dir argument is used verbatim

• CLAUDE_DESIGN_HEADLESS — set 1 to drive headless Chrome instead of off-screen

• CLAUDE_DESIGN_TURN_TIMEOUT_MS — hard cap per generation turn (create ~360s, iterate ~240s defaults)

• CLAUDE_DESIGN_QUIET_MS — how long the turn network must stay silent before a generation is judged complete (default 20000)

• CLAUDE_DESIGN_CLAUDE_BIN — Claude Code binary used by design_system_sync (default claude)

• CLAUDE_DESIGN_SYNC_TIMEOUT_MS — hard cap for one /design-sync run (default 900000, 15 minutes)

Design-system sync

design_system_sync (CLI: sync <dir>) is the one tool that does not drive the browser: it runs claude -p "/design-sync" --dangerously-skip-permissions --output-format json with the package folder as its working directory and reports what the sync uploaded.

• The folder must already be a package (package.json + a CSS entry such as styles.css, plus tokens/*.json, guidelines/*.md, README.md). Components are optional — a tokens-only package is accepted. The tool refuses before spawning if package.json is missing.

• Exit status is not the success signal. A refused sync still exits 0 with subtype: "success", so the result is only ok: true when the reply carries a real project link; otherwise you get { ok: false, error, raw } with the full output for diagnosis.

• A first run creates the project and writes .design-sync/config.json, which pins later runs to the same project (an unchanged re-run is then a no-op instead of a duplicate). If your pipeline regenerates the folder, snapshot .design-sync/ before replacing it and restore it afterwards — this tool never writes the package itself.

• A first sync takes ~10 minutes; unchanged re-runs take ~2. The CLI exits 1 on a failed sync.

design_system_list (CLI: list-systems) is the read side of the same feature. claude.ai has no separate design-systems endpoint — design systems are returned by the ordinary project list RPC tagged PROJECT_TYPE_DESIGN_SYSTEM, which pages 20 at a time, so the tool follows every page and returns [{ name, id, publishedAt?, viewedAt? }] (publishedAt appears only once a system has been published). Use it to confirm what design_system_sync actually landed on the account. scripts/probe-design-systems.mjs re-captures that live shape if the API changes.

When is a generation "done"?

claude.ai/design drives generation as turns: your prompt streams in over a Chat RPC, kept alive by RenewTurn keepalives (~every 10s) and ended by a ReleaseTurn. design_create / design_iterate return once the files have settled AND the turn network has gone quiet for CLAUDE_DESIGN_QUIET_MS — comfortably longer than the keepalive interval, so a generation is never cut off mid-write (you always get a complete, coherent design, not a half-rendered one).

If a generation reaches its hard deadline before the quiet/stability checks complete, the result includes timedOut: true. Normal completions omit the field entirely; treat its presence as a signal that the returned files are the best available snapshot at the timeout rather than a fully quiet turn.

Note that claude.ai often runs an automatic refine pass that starts ~30s after the first design settles, so the design keeps improving on the server after the tool has returned its first complete version. To get the most-refined output, design_pull / design_preview always fetch the latest state, or raise CLAUDE_DESIGN_QUIET_MS (e.g. 60000) to make create wait through later refine passes (at the cost of a longer wait).