What is Pattern MCP?
Pattern, published as pattern-mcp, is an MCP server that judges a UI need against your own registered design system, in code or in Figma. It tells the agent to use an existing component or build a custom one, and an auditable ledger records each decision.
Pattern's pitch is a question asked before the build starts: does your design system already cover this need? It scores the request against components you registered, so the agent reuses what exists and builds only what is missing.
Since version 0.18 it scores only against a design system you register. That system can be a Figma file, a components folder or a manifest, and without one the recommendation call returns an error asking you to register.
The verdicts it returns
use_existing: a registered component covers the need.custom_build: nothing fits, and the unmet requirements show what to build.no_candidates_found: kept separate from a low coverage result.skip_list: the need is a simple primitive that does not need scoring.ledger_cache_hit: a recent matching judgment was reused.
How the check works in practice
- Register your design system once with
register_design_system. - Pattern turns the request into specific requirements, or uses a checklist you supply.
- It checks each registered component's props, descriptions and Figma data against them.
- The server calculates coverage itself from the individual requirements, instead of trusting a model's percentage.
- After the build,
verify_componentchecks the file against the checklist and records the result.
Optional enforcement and a decision ledger
An opt-in hook, pattern-check-gate-hook, and a CI gate, pattern-check-gate, can make the check required instead of optional. Every decision lands in a ledger you can verify later, which suits teams that need an audit trail.
Who it is for
Best for
- Teams with a real design system, in code or Figma, whose agents keep rebuilding components that already exist.
- Projects that pair component registries such as the shadcn MCP server with a check that the registered library is used first.
- Readers who write requirement checklists in the style of a component spec skill and want a server to score against them.
Not for
- Projects with no design system yet. Pattern has nothing to judge against until you register one.
- Trivial primitives and small edits, which the server's own instructions say to skip.
Use it with UiChemy
Pattern keeps agent-written interfaces consistent with your component library. For a WordPress result, UiChemy's AI to WordPress imports an AI build, and Composer edits it inside Elementor or Gutenberg. Click Get Started on uichemy.com.
Connect Pattern MCP: Make AI Agents Reuse Your Design System Components to your AI client
npx pattern-mcp initRun init
Run
npx pattern-mcp init. It detects which MCP client you have, among Claude Code, Claude Desktop, Cursor and Codex CLI, connects each one, and offers to add your Anthropic API key.Follow the five steps
The guided setup lists them up front: your Anthropic key, a Figma token if you use Figma, connecting your client, registering your design system and the optional required check. It ends with a count of steps done.
Register your design system
Point Pattern at a Figma link, a components folder or a manifest through
register_design_system. A very large Figma file offers to leave out icon pages.Let the agent use it
The server sends short usage instructions when it connects, so the agent calls it when building UI. Set
PATTERN_NO_INSTRUCTIONS=1to turn that off.Check the setup
Run
npx -p pattern-mcp pattern doctorto confirm the server and any hook or workflow are in order.
Endpoints and ports
https://usepattern.shVendor siteWhat you can do with it
- Design system only scoringMatches are scored only against the system you registered, in code or Figma.
- Server side coverageThe server computes coverage from individual requirements it checked.
- Gap lists on custom buildsA custom_build verdict shows which requirements the closest components miss.
- Overlap safeguardA free check compares a custom_build verdict with real component names, props and descriptions.
- Post build verificationverify_component checks the finished file against the checklist item by item.
- Auditable ledgerEach decision is recorded and can be verified or exported later.
- Opt-in enforcementA hook and a CI gate can make the check required.
- Per project memoryRecorded decisions feed later recommendations in the same project.
Tools it exposes
register_design_system
Points Pattern at your design system: a Figma file, a components folder or a manifest. Core tool.
recommend_component
Judges a UI component need against the registered design system and returns a structured recommendation. Core tool.
extract_requirements
Runs only the requirement extraction step so you can inspect or edit the checklist. Core tool.
verify_component
Checks the built file against the requirement checklist, with quotes the server confirms exist in the file. Core tool.
record_component_decision
Records what the agent actually did so later recommendations in the project can use it. Core tool.
get_figma_evidence
Advanced tool, shown with PATTERN_TOOLS=full. Works with the Figma data kept at registration.
read_ledger
Advanced tool, shown with PATTERN_TOOLS=full. Reads the project's decision ledger.
report_build_cost
Advanced tool, shown with PATTERN_TOOLS=full. Part of cost tracking.
report_outcome_proxy
Advanced tool, shown with PATTERN_TOOLS=full. Part of outcome tracking.
check_ledger_liveness
Advanced tool, shown with PATTERN_TOOLS=full. Ledger liveness check.
sweep_ledger_liveness
Advanced tool, shown with PATTERN_TOOLS=full. Ledger liveness sweep.
export_ledger_provenance
Advanced tool, shown with PATTERN_TOOLS=full. Ledger provenance export.
backfill_ledger_snapshot_ref
Advanced tool, shown with PATTERN_TOOLS=full. Ledger provenance maintenance.
post_ledger_provenance_to_github
Advanced tool, shown with PATTERN_TOOLS=full. Ledger provenance posting to GitHub.
Frequently asked questions
What is Pattern MCP?
Pattern, published as pattern-mcp, is an MCP server that checks a coding agent's UI decisions against your own design system before it builds. It recommends reusing a component or building a custom one, and records the decision in a ledger.
How do I install Pattern MCP?
Run npx pattern-mcp init. It detects your MCP clients, connects them, and offers to add your Anthropic API key. Then register your design system, because Pattern has nothing to judge against until you do.
Which AI tools work with Pattern MCP?
The init command detects Claude Code, Claude Desktop, Cursor and Codex CLI and connects each one for you. The README also describes a hand setup if you would rather connect a client by hand.
Does Pattern need a design system?
Yes. Since version 0.18 it scores only against a design system you register, which can be a Figma file, a components folder or a manifest. Without one, the recommendation call returns an error that asks you to register.
Does the agent call it without being told?
The server sends short usage instructions when it connects. In the README's headless test, agents used it unprompted in 6 of 6 UI-building runs with the instructions and 0 of 6 without, with n=2 per cell.
How many tools does it have?
Fourteen. Five core tools are on by default: register_design_system, recommend_component, extract_requirements, verify_component and record_component_decision. Setting PATTERN_TOOLS=full advertises the nine advanced tools for cost, outcome and ledger work. Every tool still works when called directly by name.
Can it block work that skips the check?
Yes, optionally. An opt-in hook (pattern-check-gate-hook) and the pattern-check-gate CI check can make the call required. From version 0.22.0 the CI check also compares modified component files against the base branch for new components.
What are alternatives to Pattern MCP?
For installing components, see the shadcn MCP server. For design system tooling in general, see design system MCP servers. Pattern differs by judging whether to reuse before anything is built.