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.

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

Design-system bindings

Conversations

Files

Publish, listing & management

Related MCP server: claudecode-mcp

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.