claude-design-mcp

An MCP server that drives Claude Design — Anthropic's design-system generator — from agentic coding CLIs (Claude Code, Cursor, etc.). It exposes semantic tools so you can create_design_system, generate, iterate, list_files, read_file, and export without touching a browser.

[!WARNING] Unofficial — not affiliated with or endorsed by Anthropic. Claude Design has no public API, so this drives a real Chrome and calls claude.ai's internal endpoints. Expect it to break when the site changes. Point it only at your own account, stay within Anthropic's terms, and use it at your own risk. Your logged-in session is sensitive — see SECURITY.md.

Status: working. ~30 tools implemented (see the table below). Most call Claude Design's internal OmeletteService Connect-RPC API as JSON (via in-page fetch); generate/iterate/get_status drive the chat UI (the Chat RPC payload is opaque).

Tools

Create & generate

Tool	Purpose
create_design_system({ name, brief, sources? })	Create a design system. Returns { projectId, url }.
create_design_project({ name, brief?, designSystemIds?, designComponents? })	Create a design PROJECT (screens/app), optionally binding design systems.
generate({ projectId })	Start generation from the stored brief. Returns once started (~5 min total).
get_status({ projectId })	Poll: generating | ready | error | draft.
iterate({ projectId, prompt })	Send a chat message. Non-blocking — returns once started; poll get_status.
send_message({ projectId, prompt, conversationId? })	Revise/prompt; optionally target a specific conversation.

Design-system bindings

Tool	Purpose
attach_design_system({ projectId, designSystemId })	Bind a (published) design system to a project.
detach_design_system({ projectId, designSystemId })	Unbind a design system.
list_attached_design_systems({ projectId })	List bound systems (with names).
refresh_design_system({ projectId, designSystemId? })	Pull the latest version of bound system(s).

Conversations

Tool	Purpose
list_conversations({ projectId })	List chats: { chatId, title, turns, active }.
new_conversation({ projectId })	Start a fresh conversation.

Files

Tool	Purpose
list_files({ projectId })	List files (tokens/*.css, components/*, SKILL.md, …).
read_file({ projectId, path })	Read a single file (utf8).
export({ projectId, destDir })	Dump all files to destDir, byte-faithful.
mint_handoff({ projectId, includeChats?, instructions?, destDir? })	Primary handoff. Official capability URL + ready Claude Code command; with destDir, downloads + extracts the bundle and returns projectDir (feed to scaffold:ui).
export_handoff({ projectId, destDir })	Deprecated — local bundle (project/ + chats/ + README). Prefer mint_handoff.
search_files({ projectId, pattern })	Grep files → { path, line, context }.
write_file / edit_file / delete_file	Direct file edits without chat.

Publish, listing & management

Tool	Purpose
publish({ projectId }) / set_default({ projectId })	Publish / set default design system.
list_design_systems() / list_projects()	List design systems / all projects.
rename_project / delete_project / duplicate_project / remix_project / set_favorite	Project housekeeping.
get_usage()	Account usage/quota (5-hour & 7-day).
create_claude_code_session({ projectId, instructions? })	Open the project as a Claude Code session → { sessionUrl }.

Setup

Prerequisites: Node ≥ 20, pnpm, and a desktop Google Chrome installed. A claude.ai account with Claude Design access.

claude.ai is behind Cloudflare, which blocks Playwright's bundled Chromium (automation fingerprint) with an endless "Just a moment…" loop. The server sidesteps this by attaching to a real Chrome over the Chrome DevTools Protocol (CDP) — a normally-launched Chrome passes Cloudflare cleanly.

git clone https://github.com/e-brokenc0de/claude-design-mcp.git
cd claude-design-mcp

pnpm install
pnpm exec playwright install chromium   # only the Node bindings are needed

# Start the real Chrome (dedicated debug profile in .auth/cdp-chrome) and log
# into claude.ai once. The window stays open; the session persists.
pnpm run chrome:cdp

pnpm run build

Dev-only: pnpm run recon:capture tees Claude Design's network/RPC traffic into ./recon/ so you can re-map the internal API in src/selectors.ts if the site changes. Not needed for normal use. Captures can contain cookies — they're gitignored; never commit them.

The MCP server attaches to the same Chrome (port 9222 by default). If Chrome isn't running, the server auto-launches it; if it's not logged in, tools return NOT_AUTHED — run pnpm run chrome:cdp and log in.

CLI

Every tool is also a terminal command via claude-design. The CLI is a thin MCP client — it spawns the same server and forwards your arguments, so the commands, schemas, and output are exactly the server's (add a tool to the server and it shows up here automatically). Good for automation/CI, quick debugging, and one-off ops without an agent in the loop.

claude-design --help                  # list every command (discovered from the server)
claude-design <command> --help        # flags for one command
claude-design list-projects --json    # data tools print JSON → pipe to jq
claude-design create-design-system --name "Acme" --brief "Calm, editorial, dark-first"
claude-design get-status --project-id <id>

• Command names accept kebab- or snake_case (create-design-system == create_design_system).
• Flags mirror each tool's arguments in kebab-case (projectId → --project-id); array args repeat (--design-system-ids a --design-system-ids b); booleans are presence flags.
• --json guarantees machine-readable stdout. Exit codes: 0 ok, 1 error, 2 NOT_AUTHED.
• Same prerequisites as the server: a logged-in Chrome (claude-design chrome), and generation is async — kick off generate/iterate, then claude-design watch --project <id>.

The dev scripts are folded in as subcommands too: claude-design chrome (auth), claude-design scaffold (export → packages/ui), claude-design watch (block until a generation settles). They're equivalent to the matching pnpm run scripts.

Run it without installing globally via npx claude-design …, or node dist/cli.js … from a clone.

Scaffold a packages/ui from an export

Turn a Claude Design export (the project/ folder of a handoff bundle, or a plain export dir) into a maintainable token + UI package: DTCG tokens → Style Dictionary → Tailwind v4 @theme, plus a component skeleton. Components are scaffolded (not auto-converted) with the raw export kept under _design-source/ for Claude Code to port.

pnpm run scaffold:ui -- --src <exportDir> --out <repo>/packages --name ui --ds-name "My DS"

Produces packages/tokens (DTCG JSON source of truth + build/theme.css + tokens.ts, rebuildable with style-dictionary build) and packages/ui (styles/, primitives/, components/, index.ts, CLAUDE.md), plus a root PROMPT.md with porting steps. Primitives land in :root; semantic tokens become Tailwind utilities via @theme inline, with var() references preserved so a one-token re-theme still cascades.

Registering with Claude Code / Cursor

Copy .mcp.json into your project, or add an entry to your existing MCP config:

{
  "mcpServers": {
    "claude-design": {
      "command": "node",
      "args": ["/absolute/path/to/claude-design-mcp/dist/server.js"]
    }
  }
}

Architecture

• src/server.ts — MCP stdio server; thin tool dispatcher.
• src/backend.ts — DesignBackend interface (the contract every backend implements).
• src/browser.ts — CDP acquisition: spawn/reuse real Chrome with a debug port, attach over CDP, find the design tab.
• src/backends/cdp.ts — CDP-attached backend; reattaches per call so generations survive across tool calls.
• src/selectors.ts — ⚠️ THE ONLY PLACE selectors and endpoint patterns live. UI shifts? Edit this one file.
• src/registry.ts — Persists projectId → { url, name } across stdio invocations.
• src/config.ts / src/errors.ts — env-driven config + structured loud errors.

Once recon captures Claude Design's internal API, tool bodies wire to in-page fetch (preferred) or DOM interaction, both centralized via src/selectors.ts.

Secrets

./.auth/ (the Chrome debug profile, holding your logged-in session) and any captures in ./recon/ are gitignored. Never commit them. See SECURITY.md for the full list and reporting policy.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for dev setup and the one rule that matters: when claude.ai changes, fix src/selectors.ts first.

License

MIT © Brokenc0de. Unofficial; not affiliated with Anthropic.