What is Design System MCP?
Design System MCP is a single-process server that indexes a design-system Git repository of tokens, principles, patterns, voice guidance, prompts and rules. Coding agents query it for the right tokens and components, then validate generated UI against deterministic rules such as no raw hex colors.
The pitch is four questions an agent can now ask: which tokens belong on this button, which confirmation dialog pattern exists, what voice an empty state should use, and whether generated UI contains raw hex colors.
It is one Node.js process with no Redis, no database and no object store. The source of truth is a design-system Git repo, and the server rebuilds an in-memory bundle with a MiniSearch index on startup and refresh.
What the source repo contains
- Tokens in
tokens/*.tokens.json, resolved through Style Dictionary. - Principles, patterns and conventions as Markdown or MDX with frontmatter.
- Components with
component.jsonmetadata, plus source files in many languages. - Prompt templates in
prompts/*.prompt.mdand validation rules inrules/*.json. - A
manifest.jsonthat declares content types and relations.
Token formats it accepts
| Source style | Supported | Note |
|---|---|---|
| DTCG JSON | Yes | Resolved through Style Dictionary |
| Token Studio exports | Yes | Token-set order and contextual references |
| Markdown frontmatter tokens | Yes | Full DTCG-shaped trees |
| Prose token tables | Searchable only | Not used for deterministic resolution |
Fit and limits
Best for
- Design systems teams who want agents to use their tokens instead of inventing spacing and colors.
- CI pipelines that need a validation command with JSON or SARIF output and a nonzero exit on error.
- Readers comparing it with other design system servers or the DESIGN.md format.
- Teams that keep tokens in a repo and follow a design token skill for naming.
Not for
- Horizontal scaling, OAuth or persistent user state. The README treats those as a separate future proposal.
- A quick start with no design system. It needs a content repo to index first.
Use it with UiChemy
This server keeps agents faithful to a design system. Teams that publish on WordPress can pair that discipline with UiChemy, which turns a Figma design into an editable page. Click Get Started on uichemy.com to try it.
Connect Design System MCP: Serve Your Tokens, Patterns and Rules to Coding Agents to your AI client
pnpm install && pnpm buildCheck requirements
You need Node.js 22.0.0 or newer, pnpm 9.0.0 or newer, and git 2.5 or newer if you use DS_MCP_SOURCE_MODE=git.
Install and build
Run pnpm install and then pnpm build in a checkout of the repository.
Prepare a design-system source repo
Lay out manifest.json, tokens, docs, components, prompts and rules as shown in the README. A Markdown-only repo with a getdesign.md file also works.
Choose a source mode
Use local mode against a checked-out design-system folder, or git mode with clone and pull refresh. Use stdio for a local IDE or Streamable HTTP for hosted use.
Wire up your client
The README points to docs/client-setup.md in the repository for per-client configuration.
Validate in CI
Run pnpm validate -- --source <design-system-repo> <file...> for JSON or SARIF output and a nonzero exit on error violations.
Endpoints and ports
design://manifestDeclares content types and relationsdesign://schemaSchema of the loaded design systemdesign://workflowMachine-readable contract for design-system-first agent harnessesdesign://entity/{id}One entity by id, with per-type templates for principle, pattern, component and promptWhat you can do with it
- Deterministic design contextAgents get tokens, patterns and rules from one authoritative source instead of guessing, and decisions and violations carry provenance.
- Many token sourcesDTCG JSON, Token Studio exports, whole-token aliases, Markdown frontmatter and community Markdown sections all load into one resolved set.
- Component metadata and sourceComponent props, canonical examples, constraints and Storybook stories are indexed, and source files are returned for reuse.
- Rule-based validationJSON regex rules, AST-backed JSX prop checks and built-in semantic token, accessibility, copy and deprecation checks run on generated UI.
- Composition contractsPattern docs can require components, tokens, order and slots, and validate_composition checks them before code is written.
- Two transportsstdio serves local IDEs and Streamable HTTP serves hosted use, with optional HTTP API-key auth and health and readiness endpoints.
- Prompts and resourcesPrompt templates register as MCP prompts, and design:// resources expose the manifest, schema, entities and workflow.
Tools it exposes
resolve_token
Resolves a design token deterministically through Style Dictionary.
validate_ui
Checks generated UI against the loaded rules, including raw values, unknown CSS variables, deprecated tokens, accessibility and copy issues.
validate_composition
Enforces a pattern's frontmatter contract, such as required components, tokens and parent and child rules, before code generation.
inspect_coverage
Reports how complete the source repo is. A community profile suits Markdown-only repos, and the default enterprise profile treats missing required entity types as errors.
get_related
Walks the relation graph between entities, including references inferred from explicit ids.
get_component_source
Returns the implementation files beside a component's metadata so an agent can reuse existing code.
Frequently asked questions
What is Design System MCP?
Design System MCP is a single-instance Model Context Protocol server that gives AI coding agents authoritative design-system context. It indexes a Git repo of tokens, principles, patterns, voice guidance, prompts and rules, and checks generated UI against them.
How do I install Design System MCP?
Clone the repository, make sure you have Node.js 22 or newer and pnpm 9 or newer, then run pnpm install and pnpm build. You also need a design-system source repo to index. Client configuration is covered in docs/client-setup.md.
What does the design-system repo need to contain?
A minimal source repo has manifest.json, tokens, docs for principles, patterns and conventions, components with component.json, prompts and rules. For a lighter route, a Markdown-only repo with a getdesign.md file and frontmatter tokens also works.
Which token formats are supported?
DTCG JSON in tokens/*.tokens.json, Token Studio exports, DTCG whole-token aliases ending in .@, Markdown frontmatter tokens and community Markdown sections are supported. Markdown prose tables are searchable guidance only, not resolved tokens.
Can it run in CI?
Yes. The validation CLI, pnpm validate with a source repo and files, supports JSON and SARIF output, composition-plan validation, and exits nonzero on error violations. Performance baseline gates also run in the project's own CI.
Does it work with Claude Code, Cursor and other agents?
The README says MCP-compatible IDEs, editors and internal agents can use it, over stdio locally or Streamable HTTP when hosted. It does not name specific products, so check docs/client-setup.md for your client.
Does it generate UI code itself?
No. Component metadata gives agents stable imports, prop contracts and examples without the server generating application code. The agent writes the UI, and validate_ui and validate_composition then check the result against your rules.
Does it scale across several instances?
No. The design intentionally stays small, with a single Node.js process and in-memory state. The README says horizontal scaling, persistent user state, OAuth or external search would be a separate future proposal.