Shadcn UI v4 MCP 服务器

🚀 将 shadcn/ui 组件无缝集成到您的 AI 工作流中的最快方式

这是一款模型上下文协议 (MCP) 服务器，为 AI 助手提供对 shadcn/ui v4 组件、区块、示例和元数据的全面访问。您可以轻松获取 React、Svelte、Vue 和 React Native 的实现，以支持您的 AI 驱动开发工作流。

✨ 核心特性

• 🎯 多框架支持 - 支持 React、Svelte、Vue 和 React Native 实现
• 📦 组件源码 - 最新 shadcn/ui v4 TypeScript 源代码
• 🎨 组件示例 - 示例实现及使用模式
• 🏗️ 区块支持 - 完整区块实现（仪表板、日历、表单等）
• 📋 元数据访问 - 依赖项、描述及配置详情
• 🔍 目录浏览 - 探索仓库结构
• ⚡ 智能缓存 - 高效的 GitHub API 集成，并处理速率限制
• 🌐 SSE 传输 - 支持 Server-Sent Events，适用于多客户端部署
• 🐳 Docker 就绪 - 使用 Docker Compose 的生产就绪容器化方案

🚀 快速入门

# 基本用法（每小时 60 次请求）
npx @jpisnice/shadcn-ui-mcp-server

# 使用 GitHub Token（每小时 5000 次请求）- 推荐
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# 切换框架
npx @jpisnice/shadcn-ui-mcp-server --framework svelte
npx @jpisnice/shadcn-ui-mcp-server --framework vue
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

# 使用 Base UI 替代 Radix UI（仅限 React）
npx @jpisnice/shadcn-ui-mcp-server --ui-library base

🎯 2 分钟内获取 GitHub Token：docs/getting-started/github-token.md

📦 一键安装（Claude Desktop）

下载并双击 .mcpb 文件即可立即安装：

1. 从 Releases 下载 shadcn-ui-mcp-server.mcpb
2. 双击文件 - Claude Desktop 会自动打开
3. 输入您的 GitHub Token（可选，用于提高请求限额）
4. 点击“安装” - 工具将立即可用

手动安装：Claude Desktop → 设置 → MCP → 添加服务器 → 浏览 → 选择 .mcpb 文件

参考文献：Anthropic Desktop 扩展 | 构建 MCPB

🌐 SSE 传输与 Docker 部署

使用 Server-Sent Events (SSE) 传输运行服务器，以支持多客户端连接和生产环境部署：

SSE 模式快速启动

# SSE 模式（支持多个并发连接）
node build/index.js --mode sse --port 7423

# Docker Compose（生产就绪）
docker-compose up -d

# 使用 Claude Code 连接
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse

传输模式

• stdio（默认）- 用于 CLI 使用的标准输入输出
• sse - 基于 HTTP 的 Server-Sent Events 连接
• dual - 同时支持 stdio 和 SSE

Docker 示例

# 基础容器
docker run -p 7423:7423 shadcn-ui-mcp-server

# 带 GitHub API Token
docker run -p 7423:7423 -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token shadcn-ui-mcp-server

# Docker Compose（推荐）
docker-compose up -d
curl http://localhost:7423/health

环境变量

• MCP_TRANSPORT_MODE - 传输模式（stdio|sse|dual）
• MCP_PORT - SSE 服务器端口（默认：7423 - SHADCN 在键盘上！）
• MCP_HOST - 主机绑定（默认：0.0.0.0）
• MCP_CORS_ORIGINS - CORS 来源（逗号分隔）
• GITHUB_PERSONAL_ACCESS_TOKEN - GitHub API Token
• UI_LIBRARY - UI 基础库：radix（默认）或 base（仅限 React）

📚 文档

版块	描述
🚀 入门指南	安装、设置及第一步
⚙️ 配置	框架选择、Token 及选项
🔌 集成	编辑器及工具集成
📖 使用	示例、教程及用例
🎨 框架	各框架专用文档
🐛 故障排除	常见问题及解决方案
🔧 API 参考	工具参考及技术细节

🎨 框架支持

该 MCP 服务器支持四种流行的 shadcn 实现：

框架	仓库	维护者	描述
React（默认）	shadcn/ui	shadcn	shadcn/ui v4 的 React 组件
Svelte	shadcn-svelte	huntabyte	shadcn-svelte 的 Svelte 组件
Vue	shadcn-vue	unovue	shadcn-vue 的 Vue 组件
React Native	react-native-reusables	Founded Labs	react-native-reusables 的 React Native 组件

UI 库（仅限 React）

shadcn/ui v4 支持两种 React 基础库：Radix UI（默认）和 Base UI。

# Radix UI（默认）
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library radix

# Base UI
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library base

# 或通过环境变量
UI_LIBRARY=base npx @jpisnice/shadcn-ui-mcp-server

Claude Desktop 配置示例：

{
  "args": ["--framework", "react", "--ui-library", "base"]
}

🛠️ 必备设置

1. 获取 GitHub Token（推荐）

# 访问：https://github.com/settings/tokens
# 生成无需任何权限范围的 Token
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

2. 运行服务器

# React（默认）
npx @jpisnice/shadcn-ui-mcp-server

# Svelte
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Vue  
npx @jpisnice/shadcn-ui-mcp-server --framework vue

# React Native
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

3. 与您的编辑器集成

• Claude Code: 请参阅下方的Claude Code 集成
• VS Code: docs/integration/vscode.md
• Cursor: docs/integration/cursor.md
• Claude Desktop: docs/integration/claude-desktop.md
• Continue.dev: docs/integration/continue.md

💻 Claude Code 集成

快速添加（CLI）

# 添加 shadcn-ui MCP 服务器
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN

SSE 传输

对于使用 SSE 传输的生产部署：

# 以 SSE 模式启动服务器
node build/index.js --mode sse --port 7423

# 使用 Claude Code 连接
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse

框架特定命令

有关框架特定命令（React、Svelte、Vue、React Native），请参阅Claude Code 集成指南。

参考： Claude Code MCP 文档

🎯 使用场景

• AI 驱动开发 - 让 AI 助手使用 shadcn/ui 构建 UI
• 多客户端部署 - SSE 传输支持多个并发连接
• 生产环境 - 已准备好 Docker Compose，带有健康检查和监控
• 组件发现 - 探索可用组件及其用法
• 多框架学习 - 比较 React、Svelte、Vue 和 React Native 的实现
• 快速原型设计 - 获取仪表板、表单等的完整区块实现
• 代码生成 - 生成包含正确依赖项的组件代码

📦 安装

# 全局安装（可选）
npm install -g @jpisnice/shadcn-ui-mcp-server

# 或者使用 npx（推荐）
npx @jpisnice/shadcn-ui-mcp-server

🔨 从源码构建

先决条件

• Node.js >= 18.0.0
• npm 或 pnpm

构建步骤

# 克隆仓库
git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git
cd shadcn-ui-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行服务器
node build/index.js --github-api-key YOUR_TOKEN

本地运行

# 构建后，可带选项运行
node build/index.js --github-api-key YOUR_TOKEN
node build/index.js --framework svelte

构建 MCPB 包

该项目包含一个遵循MCPB 规范的 manifest.json 文件。.mcpb 文件是一个 ZIP 存档，包含服务器、依赖项和配置。

有关详细的打包说明，请参阅CONTRIBUTING.md。

参考： 使用 MCPB 构建桌面扩展

🔗 快速链接

• 📖 完整文档
• 🚀 入门指南
• 🌐 SSE 传输与 Docker 指南
• 🎨 框架比较
• 🔧 API 参考
• 🐛 故障排除
• 💬 问题与讨论

📄 许可证

MIT 许可证 - 详情请参阅LICENSE。

🙏 致谢

• shadcn - 感谢其出色的 React UI 组件库
• huntabyte - 感谢其优秀的 Svelte 实现
• unovue - 感谢其全面的 Vue 实现
• Founded Labs - 感谢其 React Native 实现
• Anthropic - 感谢其 Model Context Protocol 规范

---

由 Janardhan Polle 用心制作

如果您觉得本项目有帮助，请为它点亮星星 ⭐！

shadcn-ui-mcp-server 快速上手指南

shadcn-ui-mcp-server 是一个基于模型上下文协议（MCP）的服务器工具，旨在让 AI 助手（如 Claude、Cursor 等）能够直接访问和使用 shadcn/ui v4 的组件、代码块和元数据。它支持 React、Svelte、Vue 和 React Native 多种框架，是构建 AI 驱动前端工作流的高效工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 >= 18.0.0
• 包管理器: npm 或 pnpm
• GitHub Token (推荐):
  • 虽然不强制，但配置 GitHub Personal Access Token 可将 API 请求限制从每小时 60 次提升至 5000 次。
  • 获取方式：访问 GitHub Tokens 设置页，生成一个无需特定权限（no scopes needed）的 Token。

安装步骤

您可以选择全局安装或直接使用 npx 运行（推荐）。

方式一：直接使用 npx（推荐）

无需预先安装，直接在终端运行即可：

# 基础运行（限流 60 次/小时）
npx @jpisnice/shadcn-ui-mcp-server

# 推荐：携带 GitHub Token 运行（限流 5000 次/小时）
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

方式二：全局安装

如果您希望将命令添加到全局路径：

npm install -g @jpisnice/shadcn-ui-mcp-server

安装后，可直接运行 shadcn-ui-mcp-server 命令。

切换框架

该工具默认支持 React，也可通过参数切换至其他框架：

# Svelte
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Vue
npx @jpisnice/shadcn-ui-mcp-server --framework vue

# React Native
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

# React 使用 Base UI 代替默认的 Radix UI
npx @jpisnice/shadcn-ui-mcp-server --ui-library base

基本使用

安装完成后，您需要将服务器集成到您的 AI 编辑器或 IDE 中。以下是两种最常用的集成方式。

1. 集成到 Claude Code (CLI)

如果您使用 Claude Code 命令行工具，可以使用以下命令快速添加服务：

# 添加 shadcn-ui MCP 服务器（请替换 YOUR_TOKEN 为您的实际 Token）
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN

添加成功后，您可以在对话中直接要求 AI 生成 shadcn/ui 组件代码。

2. 集成到 Claude Desktop (图形界面)

对于桌面版用户，可以通过一键安装包快速配置：

1. 从 Releases 页面 下载 shadcn-ui-mcp-server.mcpb 文件。
2. 双击该文件，Claude Desktop 将自动打开。
3. 在弹出的窗口中输入您的 GitHub Token（可选，但推荐）。
4. 点击 Install，工具即刻可用。

手动安装路径：Claude Desktop → Settings → MCP → Add Server → Browse → 选择下载的 .mcpb 文件。

3. 高级用法：SSE 模式与 Docker

适用于生产环境或多客户端并发场景：

# 启动 SSE 模式服务器
node build/index.js --mode sse --port 7423

# 使用 Docker Compose 启动（需项目根目录有 docker-compose.yml）
docker-compose up -d

# 在 Claude Code 中连接 SSE 服务
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse

现在，您可以在 AI 对话中尝试输入：“帮我用 shadcn/ui 创建一个带有深色模式的登录表单”，AI 将利用该服务器获取最新的组件源码并生成代码。