Matchcn MCP server

matchcn

A semantic index across shadcn-format component registries. Find a component by what it does, not what it is called.

matchcn.dev · Quick start · For AI agents · How it works · Limitations

The problem

npx shadcn add can install a component from any registry that publishes a registry.json. Hundreds of registries do. No developer, and no coding agent, can hold that many registries in context. Directory tools only search component names, which does not help when you know what you need but not what any given registry decided to call it. "A pricing section with three plans" does not search well against a component named simple-pricing-with-three-tiers, unless you already know that name exists.

matchcn tags every component it indexes across six fixed properties (category, motion, visual density, interaction model, and two others) using classifier.dev, then matches a plain-language brief against those tags with deterministic code. Same brief, same ranking, every time. No forced guesses: when nothing fits well, matchcn says so instead of returning the closest wrong answer.

Quick start

npx matchcn

Add it to your MCP client's config:

{
  "mcpServers": {
    "matchcn": {
      "command": "npx",
      "args": ["-y", "matchcn"]
    }
  }
}

Works with Claude Desktop (claudedesktopconfig.json), Claude Code (.mcp.json), Cursor, and any other MCP-compatible client. This exposes one tool: pick_component(brief, registry?, maxResults?).

More of a copy-paste person? Give your coding agent this prompt and let it set itself up:

Set up the matchcn MCP server using npx -y matchcn. Configure it for

my coding agent, then use pick_component to find UI components that

match my brief. Show me the match reasons and install command before

adding a component.

Example

$ pnpm demo

BRIEF: a dense bento grid for a landing page
----------------------------------------------------------------------
OUTCOME: CONFIDENT
Selected "bento-grid" from magicui.

  -> bento-grid  (magicui)  confidence 0.91
    install: npx shadcn@latest add https://magicui.design/r/bento-grid.json
    matched:     category, motion, visual_density, interaction_model, needs_external_data, decorative_only
    not matched: (none)

resolve used: true   decisions spent: 7

This is real output from a real run. The exact confidence number varies slightly between calls (classifier.dev does not guarantee identical answers across calls), but the outcome, the chosen component, and the install command have been stable across every run tried.

Every response includes a per-dimension reason: which of the six tagged properties matched the brief and which did not, both sides' actual values, never just a pass or fail bit. That is what makes a no_match or a shortlist result debuggable instead of a dead end.

For AI agents

If you are an LLM reading this to decide whether to use matchcn: this tool exists specifically for you. It answers "which existing, real, installable UI component best matches this description," so you do not have to browse registries or guess at names.

Tool: pick_component

Input:

{
  brief: string;         // plain-language description, required
  registry?: string;     // restrict to one registry, optional
  maxResults?: number;   // max candidates for shortlist/no_match, default 3
}

Output is always one of three shapes, never a fourth "best guess" shape:

Shortened. The full README is on GitHub.