shadcn-registry-mcp

What it does

You talk to your AI. Your AI talks to this server. The server handles everything else.

No terminal. No broken deps. No copy-paste.

Why this exists

AI-generated UI tends to be generic. When your AI guesses at component structure instead of reading from the actual registry, you get inconsistent code that fights your design system.

Public MCP registries are a security risk. The MCP ecosystem is actively targeted by supply-chain attacks, malicious servers that disguise themselves as developer tools to exfiltrate SSH keys, tokens, and environment variables.

This server solves both:

• Accurate installs — components come directly from the official ui.shadcn.com registry, with the exact file structure, dependency tree, and CSS variables shadcn intends. No guessing.
• Conversational flow — ask for a data table, a sidebar, or an entire form kit. The server resolves transitive deps, writes all files, and runs your package manager. You stay in the conversation.
• Codebase-safe — the server reads your components.json to understand your exact project layout before writing a single file. It integrates with your structure, not against it.
• Security-hardened — network egress is locked to ui.shadcn.com only. Path traversal is blocked. Package installs use execFile(), never shell concatenation. Your environment stays yours.

Who is this for

Frontend and full-stack developers who use shadcn/ui and want their AI assistant to actually install components correctly, with full dependency resolution, proper file placement, and zero security compromises.

If you've ever had an AI tell you to "run npx shadcn@latest add button" mid-conversation, this is for you.

Quick Start

Prerequisites

• Node.js 18+ · check with node --version
• A shadcn/ui project · run npx shadcn@latest init if not already set up

Step 1 — Add to your AI client

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn-registry-mcp"]
    }
  }
}

claude mcp add shadcn -- npx -y shadcn-registry-mcp

claude mcp add shadcn --scope global -- npx -y shadcn-registry-mcp

claude mcp list
# shadcn   npx -y shadcn-registry-mcp   connected ✓

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn-registry-mcp"]
    }
  }
}

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn-registry-mcp"]
    }
  }
}

Step 2 — Verify it's working

Ask your AI:

"List my installed shadcn components"

The MCP server will respond directly. If the AI runs npx shadcn@latest in a terminal instead, the server isn't connected — see Troubleshooting below.

Troubleshooting

failed to connect in claude mcp list npx cached a "not found" result from before the package was installed. Fix:

claude mcp remove shadcn
claude mcp add shadcn --scope global -- npx -y shadcn-registry-mcp@latest

components.json not found The server needs a shadcn-initialized project. Run npx shadcn@latest init in your project root first.

AI uses the terminal instead of the MCP Be explicit: "Use the add_component tool to install [name]". Some agents default to the CLI if the prompt is ambiguous.

Server disappears after restarting Claude Code You added it at project scope. Re-add with --scope global to make it persistent.

Tools

Eight tools are exposed to your AI assistant:

// Preview before writing anything
add_component({ names: ["sidebar", "button"], dryRun: true })

// Install an entire group at once
add_component({ group: "form" })  // input, textarea, select, checkbox, label, form…

Groups: form · layout · navigation · overlay · data · feedback · typography

Security

The MCP ecosystem has a supply-chain problem. Malicious servers disguise themselves as developer tools to steal credentials, SSH keys, and environment secrets. This server is built with that threat model in mind:

Compatibility

Works with Next.js (App + Pages Router), Vite, and plain React. Auto-detects npm, pnpm, yarn, and bun from your lockfile.

Custom Registries

Point to an internal design system via components.json:

{ "registryUrl": "https://registry.company.com/r" }

Or via env var (useful in CI):

{ "env": { "SHADCN_REGISTRY_URL": "https://registry.company.com/r" } }

Custom registry is checked first; the official shadcn registry is the fallback, internal and standard components work side by side.

Architecture

src/
├── index.ts              Entry point — stdio transport, process lifecycle
├── server.ts             McpServer — all 8 tools registered with Zod schemas
├── types.ts              Typed interfaces + error classes (SecurityError, CircularDepError…)
│
├── tools/                Thin handlers — validate input, compose modules, format output
│   ├── add-component.ts  Installs by name list or group · "did you mean?" on typos
│   ├── remove-component.ts  Uninstalls by name · path-validated deletion
│   ├── detect-project.ts
│   ├── get-component-info.ts
│   ├── list-components.ts
│   ├── list-installed.ts
│   └── search-components.ts
│
├── registry/
│   ├── client.ts         HTTPS-only fetch · host whitelist · 5-min cache · 2× retry
│   ├── resolver.ts       Recursive dep tree · cycle detection · Levenshtein suggestions
│   └── groups.ts         7 predefined groups
│
├── project/
│   ├── analyzer.ts       Walks up to components.json · framework + pkg manager detection
│   └── scanner.ts        Checks installed components by scanning configured directories
│
└── writer/
    ├── file-writer.ts    Path-validated writes · dry-run support
    ├── file-remover.ts   Path-validated deletion
    ├── css-writer.ts     Idempotent CSS variable merging
    └── pkg-installer.ts  execFile-based installs · per-package fallback

tests/
├── registry/client.test.ts       Fetch, caching, security, custom registry
├── project/analyzer.test.ts      Framework + pkg manager detection
├── writer/file-writer.test.ts    Path validation and write logic
├── writer/file-remover.test.ts   Path traversal security + deletion
└── e2e/
    ├── add-component.test.ts     Full pipeline: dry-run, install, skip, transitive deps
    ├── remove-component.test.ts  Delete, no-op, partial, multi-component
    └── detect-project.test.ts    Framework detection, alias resolution, missing config

Development

git clone https://github.com/Rachidhssin/shadcn-registry-mcp
npm install

npm run dev          # Run with tsx — no build step needed
npm run build        # Compile TypeScript → dist/
npm test             # Run 42 tests (unit + E2E)
npm run test:watch   # Watch mode
npm run pack:bundle  # Build + create shadcn-registry-mcp.mcpb bundle

Contributing

Contributions are welcome and appreciated. Here's how to get involved:

1. Star the repo — if this saves you time, a star helps others find it and keeps the project going.
2. Report issues — found a bug or a component that doesn't install correctly? Open an issue.
3. Submit a PR — fork → branch → write tests → open a PR. Both npm test and npm run build must pass cleanly.
4. Suggest features — have an idea for a new tool or integration? Start a discussion in the issues tab.

Security note: All security properties (network egress locking, path validation, shell safety) must be preserved in every PR. New network destinations, filesystem paths, or shell invocations require explicit justification in the PR description.