claude-design-mcp
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., "@claude-design-mcp Design a landing page and pull the files into the repo"
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.
claude-design-mcp
Talk to Claude Design from Claude Code. Send it design instructions, read what it says back, pull the files it makes into your repo, and put the right screen on your display so you can watch it work.
Claude Design is a separate product from Claude Code. It has its own projects, its own chats, and its own files, and no API. So the two never met.
This is the bridge. Claude Code can now ask the designer for a screen, watch it being drawn, read the reasoning, and pull the result straight into the codebase.
you → Claude Code → claude.ai/design → a design
← its reply, its files ←Install
/plugin marketplace add marvin-socialista/claude-design-mcp
/plugin install claude-design@claude-designThen once, in the installed plugin directory:
npm install # Playwright and the MCP SDK
npm run seed # copy your claude.ai session into the tool's browser profile
npm run smoke # read-only check, spends nothingnpm install is not optional and not automatic: this drives a real browser, so
Playwright has to be there.
seed copies only claude.ai cookies out of a Chrome profile you already use
(~/.claude/playwright-profile by default, or pass another path). Nothing else
from that profile is read or duplicated. If it is not signed in, or the session
later expires, npm run login opens a window so you can sign in by hand.
git clone https://github.com/marvin-socialista/claude-design-mcp
cd claude-design-mcp && npm install && npm run seed
claude mcp add claude-design --scope user -- node "$PWD/src/index.mjs"Related MCP server: Herald
Tools
Start something
Tool | What it does |
| The home-screen tiles: Blank, Mobile app design, Slides, Wireframe, Diagram and 9 more |
| The "What should we create?" box: a prompt, an optional template, and it starts building |
| An empty design-system project. Type is fixed at creation, so it cannot be converted later |
| Attach design systems to a project so its chats design against them |
| Attach a local folder as the project's codebase, so it designs against your real code |
| Point a project at a connected GitHub repository |
| Push a Figma |
Talk to it
Tool | What it does |
| Every project, with its |
| Chat threads in a project, marking the active one |
| Make a different thread active, since |
| Send an instruction, wait for the answer, return the reply and what changed. Takes local |
| Tail of a transcript. How you read what Claude Design said |
See and read what it built
Tool | What it does |
| The rendered page as an image, so Claude can actually judge the design |
| Put the window on your display, on a given project, chat and page |
| Grep the project's files, with line numbers and context |
| Read a file, or a line range of one, without downloading it |
| Recursive file listing |
Move work around
Tool | What it does |
| Download files to a local directory, binaries included |
| Push files up, e.g. components into a design system |
| Shut the background Chrome and flush its profile |
Delete (permanent, no trash, no undo)
Tool | What it does |
| Delete a project or design system. Requires |
| Delete files from a project, verifying they are gone |
| Delete one chat thread and its transcript |
delete_project is guarded the way GitHub guards repo deletion. A UUID is easy
for an agent to carry over from the wrong step; a name has to be looked up and
matched deliberately. Verified: it refuses "Bridge test DS" when the project
is actually called "Bridge test DS (safe to delete)".
The plugin also ships a claude-design skill that teaches Claude when and how
to reach for these, so you can just say what you want.
Attaching a local folder, without a native file dialog
"Link local code" has no file input. Its browse… calls
window.showDirectoryPicker(), a native OS dialog that no automation can drive,
which normally ends the story.
So the picker is replaced. link_local_code reads the folder in Node, then
injects a synthetic FileSystemDirectoryHandle implementing the parts the app
uses (values, entries, getFileHandle, getDirectoryHandle,
queryPermission) and overrides showDirectoryPicker to return it. The handle
is given the real prototype via Object.setPrototypeOf, so an instanceof
check still passes while our own methods shadow the native ones, which would
throw on a foreign object.
Verified end to end: after attaching src/, Claude Design listed all five
files and quoted the first line of session.mjs correctly.
Text files only, skipping .git, node_modules and build output, bounded by
file count and total bytes. Point it at a frontend or design-system folder
rather than a monorepo.
The handle is synthetic and lives in the page. A real one is persisted and re-permissioned across sessions; this one is not, so re-attach if a later session needs the files again.
Seeing the work, not just hearing about it
screenshot returns the rendered page as an image, so Claude Code can judge
layout, spacing, type and colour instead of trusting the reply text. Use
width: 402 for an iPhone-class frame, format: "png" to read fine type, and
fullPage: true with savePath for a long document.
search_code plus read_file covers the other half: read the markup Claude
Design actually wrote, without pulling anything to disk. A .dc.html page runs
to hundreds of KB, so grep first, then read the region.
Watching it work
The browser sits parked offscreen while data is read, so nothing interrupts you.
open_screen moves it onto the display over CDP rather than relaunching, and
send_prompt defaults to visible: true.
Open the screen the work is about before sending the prompt, so you watch it
change instead of being shown the result afterwards. Page names in the switcher
drop the extension: ask for Prototype.dc.html and it matches the page listed
as "Prototype".
How it works
There is no public API. What follows was worked out by reading the app's own network traffic and shipped bundle.
claude.ai/design speaks a Connect-RPC service,
anthropic.omelette.api.v1alpha.OmeletteService. Plain cookie auth, no extra
headers. The useful methods:
Method | Shape |
|
|
|
|
|
|
|
|
| server-streaming, the generation endpoint |
Reads go over the RPC. Sending a prompt goes through the real page. That split is the whole design, and it is not laziness.
Chat does not take a prompt string. It takes messagesRequest, a bytes field
holding the entire model request the client assembles, and it streams
tool_delta / tool_block_complete events back. The browser executes those
tools. The bundle contains the client-side executor (case 'local_read': …)
for roughly twenty of them: reading and writing project files, grep, screenshots,
check_design_system, generate_image, the Figma bridge. The agent loop lives
in the page.
Calling Chat directly would therefore mean reimplementing Claude Design's
harness: its system prompt, every tool schema, every tool implementation, and
the turn lifecycle (CancelChat, ReleaseTurn, the park-and-wake path). That is
cloning the app. Driving the page instead gets all of it for free, and costs one
Chrome process.
Knowing when it has finished
Two signals, both required.
Network quiet is tracked with a PerformanceObserver on resource timings, which
is how the app itself watches its own stream: entries are reported on
completion, so a new …/Chat entry means a stream just ended. One user turn is
several streams (model asks for a tool, browser runs it, next stream carries the
result), so quiet means "no stream has ended for idleSeconds".
Quiet alone is a trap, though. A long tool call is silent, so a turn in
flight can look finished. The decisive signal is an assistant message with
content actually landing in the transcript. Only when both hold does
send_prompt return.
No fetch patching anywhere, so nothing here can break the page.
Why the browser is visible
Chrome runs headed but parked offscreen at -2400,-2400. This is not
cosmetic: Cloudflare serves headless Chrome a 403 challenge on claude.ai even
with a valid session and stealth evasions loaded. Verified both ways, headless
403 and headed 200.
Env var | Effect |
| Start with the window on screen |
| Force headless. Expect Cloudflare to block it |
| Browser profile name (default |
| Reuse an existing Chrome profile directory instead. One Chrome per directory, so that browser must be closed first |
Limits worth knowing
This rides an internal, undocumented API. It can change without notice and there is no support if it does.
It spends your normal Claude credits and is subject to the usual rate limits.
Do not close the browser mid-turn. The browser is the agent's tool executor, so killing it aborts the work in progress and no reply is saved.
send_promptposts into the project's active chat. PasschatIdto aim it, which clicks through the chat-history popover, since no URL selects a chat (?chat=,/c/<id>and/chat/<id>all load the project and leave the previous thread selected). Creating a new chat is not automated.File entries carry no version or mtime, so
send_promptreports files added and removed accurately but cannot see an in-place edit. The reply text is what tells you those.The page switcher lists pages, not every file. Use
pull_filesfor the rest.HTML comes back with Claude Design's own preview runtime bolted to the front, a
data-omelette-injectedstyle and script pair worth about 15 KB.read_filestrips it; passraw: trueto keep it.WriteFilestakesmutationswith awriteoneof, and itsdatais a plain string, not proto bytes. Both mistakes fail silently, returning 200 while storing an empty file or the literal base64.write_filestherefore reads back what it wrote and raises if nothing landed.
Support
If this saved you time, you can buy me a coffee ☕.
License
MIT
Available Tools
23 toolschoose_repositoryDesign against a GitHub repositoryA
Point a project at one of the connected GitHub repositories, so new designs start from the product that already exists. Requires GitHub to be connected on the account already; this will not perform an OAuth grant.
Inputs: repo (required), projectId (required), visible.
close_browserClose the Claude Design browserA
Shut the background Chrome down and flush its profile. Call this when you are done for a while.
Inputs: no named parameters.
create_design_systemCreate a design systemA
Create an empty design-system project. A project type is fixed at creation and cannot be changed later, so a design system has to be made as one from the start. Push components into it with write_files, then attach it to projects with link_design_systems so their chats design against it.
Inputs: name (required).
create_projectCreate a new Claude Design projectA
Start a brand new project from the home screen: pick a template, describe what to create, and it begins building. Returns the new projectId. Claude Design names the project from your prompt. Attach local images (screenshots, references) with attachments to design from them.
Inputs: prompt (required), wait, visible, maxChars, +4 more.
delete_chatDelete a chat threadA
Permanently delete one chat thread from a project, including its transcript. No undo.
Inputs: chatId (required), projectId (required).
delete_filesDelete files from a projectA
Permanently delete files from a Claude Design project. No undo. Verifies they are gone.
Inputs: paths (required), projectId (required).
delete_projectDelete a projectA
Permanently delete a Claude Design project or design system. There is no trash and no undo. Ask the user before calling this, then pass the project's exact current name as confirmName: the call is refused if it does not match, which is what stops the wrong project being deleted.
Inputs: projectId (required), confirmName (required).
link_design_systemsAttach design systems to a projectA
Set which design systems a project designs against. Replaces the current set, so pass every one you want kept. Pass an empty list to detach all.
Inputs: projectId (required), designSystemIds (required).
link_local_codeAttach a local folder as the codebaseA
Attach a folder from this machine to a Claude Design project, so it designs against your real code. Sends text files only, skipping .git, node_modules and build output, bounded by file count and total size. Point it at the frontend or design-system folder rather than a whole monorepo.
Inputs: dir (required), projectId (required), visible, maxBytes, +1 more.
list_chatsList chats in a projectA
List the chat threads inside one Claude Design project, newest first, marking which one is active.
Inputs: projectId (required).
list_filesList project filesB
List the files in a Claude Design project.
Inputs: projectId (required), prefix.
list_projectsList Claude Design projectsA
List every claude.ai/design project you can open, with its projectId and whether it is a design system. Start here to pick the right project.
Inputs: kind.
list_templatesList project templatesA
The template tiles on the Claude Design home screen (Blank, Mobile app design, Slides, Wireframe, Diagram and the rest). Use before create_project to pick one by name.
Inputs: no named parameters.
open_screenShow a screen on the user's displayA
Bring the Claude Design window on screen and open a project, optionally a specific chat and a specific file, so the user can watch. Use this before send_prompt when the user should see the work happen, and to show them a finished screen. The browser normally sits parked offscreen, so nothing is visible until this is called.
Inputs: projectId (required), path, chatId, visible.
pull_filesPull project files to diskA
Download files from a Claude Design project into a local directory, preserving paths. Handles binaries.
Inputs: dest (required), projectId (required), paths, prefix.
read_chatRead a Claude Design chatA
Read what Claude Design has said. Returns the tail of the transcript for one chat. This is the read side of the conversation: use it after send_prompt, or on its own to catch up on what was discussed in the browser.
Inputs: projectId (required), limit, chatId, maxChars, +1 more.
read_fileRead the built codeA
Read a file straight out of a Claude Design project, no download needed. A .dc.html page runs to hundreds of KB, so use offset/limit to read a slice, and search_code first to find the line you want.
Inputs: path (required), projectId (required), raw, limit, +2 more.
screenshotSee the designA
Capture what a page in a Claude Design project actually looks like and return it as an image, so you can judge the work rather than taking the designer's word for it. Use it after send_prompt to check the result, before sending a revision so your critique is specific, and whenever the user asks whether something looks right. Captures the rendered design out of the viewer, without the app's own UI around it.
Inputs: projectId (required), path, width, chatId, +6 more.
search_codeSearch the built codeA
Grep the project's own files for a regex and get back matches with line numbers and context. This is how you find what Claude Design actually built without downloading anything: locate the markup or token, then read_file that region.
Inputs: pattern (required), projectId (required), flags, prefix, +2 more.
send_promptSend instructions to Claude DesignA
Give Claude Design an instruction in one project and wait for it to finish, then return what it said and which files it touched. It runs its own agent loop (reading and writing project files, taking screenshots), so a single prompt can take minutes. Sends into the project's active chat.
Inputs: prompt (required), projectId (required), wait, chatId, +6 more.
switch_chatSwitch the active chatA
Make a different chat thread active in a project. send_prompt always posts into the active chat, so use this to aim it at the right conversation.
Inputs: chatId (required), projectId (required).
upload_figUpload a .fig fileB
Push a Figma .fig file from disk into a project through the import menu.
Inputs: path (required), projectId (required), visible.
write_filesWrite files into a projectA
Write or overwrite files in a Claude Design project or design system. Use to push components, tokens or assets up from the repo. Overwrites without asking, so read first if unsure.
Inputs: files (required), projectId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Every tool targets a distinct resource and action: list_* covers different entities, delete_* differentiates by object, and read_chat vs read_file vs screenshot are clearly separate. No two tools appear to do the same thing.
All tool names follow a consistent verb_noun snake_case pattern (list_chats, create_project, delete_files, etc.), with only minor exceptions like screenshot that are still readable and predictable.
At 23 tools, the set is within the 16-25 range that feels heavy for a typical MCP server. While each tool seems necessary for the broad domain, the count is borderline and may overwhelm agents.
Core workflows for projects, chats, files, design systems, and external links are covered, but there are minor gaps: no explicit create_chat tool for starting a fresh thread in an existing project, and no list_repositories to discover available GitHub repos before choosing one.
Maintenance
Related MCP Connectors
Serves your design system and coding standards to coding agents, so they stop guessing.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- FlicenseAqualityNot gradedmaintenanceBridges Claude Desktop, Claude Code CLI, and Claude Code for VS Code, enabling developers to plan in Desktop, save specs to project directories, and invoke Claude Code CLI with seamless state sharing across interfaces.4-
- AlicenseNot gradedqualityFmaintenanceThe self-hosted MCP bridge between Claude Chat and Claude Code.46AGPL 3.0
- FlicenseAqualityDmaintenanceBridges Claude Design projects into existing Claude Desktop sessions by fetching code files, chat history, and project bundles.71-
- FlicenseBqualityCmaintenanceDrives the real Claude Design web app from your editor or agent, enabling creation, iteration, and retrieval of designs generated on your own claude.ai account via automated browser interaction.1010-