shadcn-registry-mcp

<div align="center"> <img src="assets/logo.svg" alt="shadcn-registry-mcp" width="160" /> <h1>shadcn-registry-mcp</h1> </div>

<br/>

<div align="center"> <video src="https://github.com/user-attachments/assets/b2503cec-b7f4-425e-8c5c-db7a968d747f" width="700" controls autoplay loop muted></video> </div>

<br/>

<div align="center">

Your AI shouldn't need a terminal.

shadcn-registry-mcp is a secure MCP server that gives AI coding assistants (Claude, Cursor, Windsurf, and more) direct access to the shadcn/ui registry, fetching, installing, and wiring up components without a single context switch.

</div>

---

What it does

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

<div align="center"> <img src="assets/diagram.svg" alt="How shadcn-registry-mcp works" width="600"/> </div>

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

<details> <summary>🖥️  <strong>Claude Desktop</strong></summary> <br/>

Open your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the shadcn entry under mcpServers:

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

Quit and relaunch Claude Desktop after saving.

</details>

<details> <summary>💻  <strong>Claude Code</strong></summary> <br/>

For the current project only:

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

For all projects (recommended):

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

Confirm it connected:

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

If the status shows failed, npx may have a stale cache. Fix: claude mcp remove shadcn then re-add with npx -y shadcn-registry-mcp@latest.

</details>

<details> <summary>🖱️  <strong>Cursor</strong></summary> <br/>

Edit .cursor/mcp.json in your project root (create it if it doesn't exist):

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

Restart Cursor after saving.

</details>

<details> <summary>🌊  <strong>Windsurf</strong></summary> <br/>

Edit ~/.codeium/windsurf/mcp_config.json:

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

Restart Windsurf after saving.

</details>

<details> <summary>📦  <strong>One-click install (.mcpb)</strong></summary> <br/>

Download shadcn-registry-mcp.mcpb from the latest release and open it — no terminal, no config editing. Works with any client that supports the .mcpb format.

</details>

---

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:

Tool	What it does	Writes
detect_project	Framework, package manager, component dirs, shadcn config	—
list_components	All available components, filterable by category	—
list_groups	Predefined groups for bulk installs	—
search_components	Find by name or keyword, ranked by relevance	—
get_component_info	Files, deps, CSS vars, install status in your project	—
add_component	Install components or groups with full dep resolution; supports dryRun	✓
remove_component	Clean uninstall — deletes component files	✓
list_installed	What's already in your project	—

// 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:

Control	What it prevents
Network egress locked to ui.shadcn.com	Registry data or tool inputs cannot trigger requests to attacker-controlled domains
Path traversal prevention	Registry-supplied paths are validated and resolved against the project root, no ../../.ssh escapes
No shell injection	execFile() with a typed args array; package names from the registry cannot inject shell commands
No stdout pollution	All logging goes to stderr; the stdio JSON-RPC channel is never corrupted
Minimal filesystem scope	Reads only components.json, package.json, and their referenced directories
Zod input validation	Every tool input is schema-validated before any code runs

---

Compatibility

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

Client	Status
Claude Desktop	✅
Claude Code	✅
Cursor	✅
Windsurf	✅
Any MCP-compatible client	✅

---

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.

---

<div align="center">

If this project helped you, consider giving it a ⭐ it means a lot.

<br/>

MIT  ·  Built with the MCP TypeScript SDK  ·  Powered by the shadcn/ui registry

</div>