Shadcn Registry MCP

shadcn-registry-mcp

](https://www.npmjs.com/package/shadcn-registry-mcp)     ](package.json)

你的AI不需要终端。

shadcn-registry-mcp 是一个安全的MCP服务器，它允许AI编码助手（Claude、Cursor、Windsurf等）直接访问shadcn/ui注册表，无需进行任何上下文切换即可获取、安装和连接组件。

______________________________________________________________________

它做什么

你与你的AI对话。你的AI与此服务器对话。服务器处理其他所有事务。

没有终端。没有损坏的deps。没有复制粘贴。

______________________________________________________________________

为什么存在

人工智能生成的UI往往是通用的。 当你的AI猜测组件结构而不是从实际的注册表中读取时，你会得到不一致的代码，这会与你的设计系统产生冲突。

公共MCP注册表存在安全风险。 MCP生态系统是供应链攻击的积极目标，恶意服务器伪装成开发人员工具，以窃取SSH密钥、令牌和环境变量。

此服务器解决了以下两个问题：

• 准确安装 --组件直接来自官方 ui.shadcn.com 注册表，具有精确的文件结构、依赖树和shadcn想要的CSS变量。没有猜测。
• 会话流 --要求提供数据表、侧边栏或整个表单工具包。服务器解析可传递的deps，写入所有文件，并运行包管理器。你留在谈话中。
• 代码库安全 --服务器读取您的 components.json 在编写单个文件之前，了解您的确切项目布局。它与你的结构融为一体，而不是与之对立。
• 加强安保 --网络出口已锁定到 ui.shadcn.com 只有。路径遍历被阻止。软件包安装使用 execFile()，永远不要连接shell。你的环境始终属于你。

______________________________________________________________________

这是给谁的

前端和全栈开发人员使用shadcn/ui，希望他们的AI助手能够正确安装组件，具有完全的依赖关系解析、正确的文件放置和零安全隐患。

如果你曾经有过人工智能告诉你“跑步” npx shadcn@latest add button“谈话中，这是给你的。

______________________________________________________________________

快速开始

先决条件

• Node.js 18+ ·检查一下 node --version
• shadcn/ui项目 ·奔跑 npx shadcn@latest init 如果尚未设置

______________________________________________________________________

步骤1——添加到您的AI客户端

🖥️ Claude Desktop

打开配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

添加 shadcn 进入下 mcpServers:

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

退出并重新启动 保存后的克劳德桌面。

💻 Claude Code

仅适用于当前项目：

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 ✓

如果状态显示 failed，npx可能有一个过时的缓存。修复： claude mcp remove shadcn 然后重新添加 npx -y shadcn-registry-mcp@latest.

🖱️ Cursor

编辑 .cursor/mcp.json 在项目根目录中（如果不存在，则创建它）：

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

保存后重新启动Cursor。

🌊 Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json:

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

保存后重新启动Windsurf。

📦 One-click install (.mcpb)

下载 shadcn-registry-mcp.mcpb 从 最新版本 打开它——没有终端，没有配置编辑。与任何支持 .mcpb 格式。

______________________________________________________________________

第二步——验证它是否正常工作

问你的AI：

*“列出我安装的shadcn组件”*

MCP服务器将直接响应。如果AI运行 npx shadcn@latest 在终端中，服务器没有连接——请参阅下面的故障排除。

______________________________________________________________________

故障排除

failed to connect 在 claude mcp list npx在安装包之前缓存了一个“找不到”的结果。修复：

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

components.json not found 服务器需要一个shadcn初始化项目。跑 npx shadcn@latest init 首先在你的项目根目录中。

AI使用终端而不是MCP 明确： *“使用 add_component 安装工具\[名称\]“*。如果提示不明确，某些代理默认使用CLI。

重新启动Claude Code后服务器消失 您在项目范围内添加了它。重新添加 --scope global 使其持久。

______________________________________________________________________

工具

您的AI助手可以使用八种工具：

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

组： form · layout · navigation · overlay · data · feedback · typography

______________________________________________________________________

安全

MCP生态系统存在供应链问题。恶意服务器伪装成开发人员工具，窃取凭据、SSH密钥和环境机密。此服务器在构建时考虑了该威胁模型：

______________________________________________________________________

兼容性

适用于 Next.js （应用+页面路由器）， 维特，以及简单的React。 自动检测 npm, pnpm, 纱线，以及 小圆面包 从你的锁文件中。

______________________________________________________________________

自定义注册表

通过以下方式指向内部设计系统 components.json:

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

或者通过env-var（在CI中很有用）：

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

首先检查自定义注册表；官方的shadcn注册表是回退，内部和标准组件并行工作。

______________________________________________________________________

建筑

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

______________________________________________________________________

发展

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

______________________________________________________________________

贡献

我们欢迎并感谢您的贡献。以下是如何参与其中：

1. 标记回购 --如果这能节省你的时间，一颗星星会帮助别人找到它，并让项目继续进行。
2. 报告问题 --发现错误或组件安装不正确？ 打开一个问题.
3. 提交PR --叉子→ 分支→ 编写测试→ 打开一个PR。两者都有 npm test 和 npm run build 必须干净利落地通过。
4. 建议功能 --对新工具或集成有想法吗？在问题选项卡中开始讨论。

安全说明： 所有安全属性（网络出口锁定、路径验证、外壳安全）都必须在每个PR中保留。新的网络目标、文件系统路径或外壳调用需要在PR描述中明确说明理由。

______________________________________________________________________

如果这个项目对你有帮助，考虑给它一个⭐ 这意味着很多。