Shadcn UI MCP Server

Shadcn UI v4 MCP 服务

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

一种 Model Context Protocol（MCP）服务，为 AI 助手提供对 shadcn/ui v4 组件、区块、演示和元数据的全面访问。为 AI 驱动的开发工作流无缝检索 React、Svelte、Vue 和 React Native 实现。

✨ 主要功能

• 🎯 多框架支持 - 支持 React、Svelte、Vue 和 React Native 实现
• 📦 组件源代码 - 最新的 shadcn/ui v4 TypeScript 源代码
• 🎨 组件演示 - 示例实现和用法模式
• 🏗️ 区块支持 - 完整的区块实现（仪表盘、日历、表单）
• 📋 元数据访问 - 依赖项、描述和配置详情
• 🔍 目录浏览 - 浏览代码库结构
• ⚡ 智能缓存 - 高效集成 GitHub API 并处理速率限制，同时在列表和读取结果中提供协议缓存提示（ttlMs/cacheScope）
• ⌨️ 参数补全 - 为提示词和资源模板参数提供自动补全（组件名称、包管理器、构建工具等）
• 🌐 Streamable HTTP 传输 - 面向多客户端部署的无状态 /mcp 端点（MCP 规范 2026-07-28）
• 🐳 支持 Docker - 通过 Docker Compose 实现可用于生产环境的容器化

🚀 快速开始

# Basic usage (60 requests/hour)
npx @jpisnice/shadcn-ui-mcp-server

# With GitHub token (5000 requests/hour) - Recommended
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# Switch frameworks
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

# Use Base UI instead of Radix (React only)
npx @jpisnice/shadcn-ui-mcp-server --ui-library base

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

📦 一键安装（Claude Desktop）

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

1. 从 Releases 下载 shadcn-ui-mcp-server.mcpb
2. 双击该文件，Claude Desktop 将自动打开
3. 输入 GitHub 令牌（可选，可提高速率限制）
4. 点击安装，即可立即使用工具

**手动安装：**Claude Desktop → Settings → MCP → Add Server → Browse → Select .mcpb file

参考资料：Anthropic Desktop Extensions | Building MCPB

🌐 HTTP 传输与 Docker 部署

该服务实现了 2026-07-28 MCP 规范（通过 MCP TypeScript SDK v2），并与 2025 年时代的客户端保持兼容。若要让客户端使用现代协议或强制使用该协议，请参阅现代协议指南。除 stdio 外，它还可以通过单个无状态 /mcp 端点提供 Streamable HTTP，用于多客户端和生产环境部署：

使用 HTTP 快速开始

# HTTP mode (stateless, supports many concurrent clients)
node build/index.js --mode http --port 7423

# Docker Compose (production ready)
docker-compose up -d

# Connect with Claude Code
claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp

传输模式

• stdio（默认）- 用于命令行的标准输入/输出
• http - 在 /mcp 上使用 Streamable HTTP
• dual - 同时使用 stdio 和 HTTP

旧版 SSE 传输（/sse + /message）已移除。--mode sse 仍可作为已弃用的 http 别名使用。

Docker 示例

# Basic container
docker run -p 7423:7423 shadcn-ui-mcp-server

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

# Docker Compose (recommended)
docker-compose up -d
curl http://localhost:7423/health

环境变量

• MCP_TRANSPORT_MODE - 传输模式（stdio|http|dual）
• MCP_PORT - HTTP 服务端口（默认值：7423——在数字键盘上对应 SHADCN！）
• MCP_HOST - 主机绑定地址（默认值：0.0.0.0）
• MCP_CORS_ORIGINS - CORS 来源（以逗号分隔）
• MCP_PROTOCOL - 接受的协议版本：any（默认值；2026-07-28 加上 2025 年版本回退）或 modern（仅 2026-07-28）。CLI：--protocol
• GITHUB_PERSONAL_ACCESS_TOKEN - GitHub API 令牌
• UI_LIBRARY - UI 原语库：radix（默认值）或 base（仅限 React）

📚 文档

章节	描述
🚀 快速入门	安装、设置和入门步骤
⚙️ 配置	框架选择、令牌和选项
🔌 集成	编辑器和工具集成
📖 使用方法	示例、教程和使用场景
🎨 框架	特定框架的文档
🐛 故障排除	常见问题及解决方案
🔧 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 (default)
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library radix

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

# Or via environment variable
UI_LIBRARY=base npx @jpisnice/shadcn-ui-mcp-server

Claude Desktop 配置示例：

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

🛠️ 基本设置

1. 获取 GitHub 令牌（推荐）

# Visit: https://github.com/settings/tokens
# Generate token with no scopes needed
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

2. 运行服务

# React (default)
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. 与编辑器集成

• Autohand Code：请参阅下文的 Autohand Code 集成
• 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

💻 Autohand Code 集成

使用 Autohand Code CLI 添加 shadcn/ui MCP 服务：

autohand mcp add shadcn bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN

在 shadcn 前添加 --scope project，即可将服务保存到当前项目的 .autohand 配置中，而不是保存到用户配置中。

💻 Claude Code 集成

快速添加（CLI）

# Add the shadcn-ui MCP server
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN

HTTP 传输

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

# Start server in HTTP mode
node build/index.js --mode http --port 7423

# Connect with Claude Code
claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp

特定框架的命令

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

参考：Claude Code MCP 文档

🎯 使用场景

• AI 驱动开发 - 让 AI 助手使用 shadcn/ui 构建 UI
• 多客户端部署 - 无状态 HTTP 传输支持水平扩展，无需粘性会话
• 生产环境 - 可直接使用 Docker Compose，内置运行状况检查和监控
• 组件发现 - 浏览可用组件及其用法
• 多框架学习 - 比较 React、Svelte、Vue 和 React Native 的实现
• 快速原型设计 - 获取仪表板、表单等的完整代码块实现
• 代码生成 - 生成依赖项配置正确的组件代码

📦 安装

# Global installation (optional)
npm install -g @jpisnice/shadcn-ui-mcp-server

# Or use npx (recommended)
npx @jpisnice/shadcn-ui-mcp-server

🔨 从源代码构建

前置条件

• Node.js >= 20.0.0
• npm 或 pnpm

构建步骤

# Clone the repository
git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git
cd shadcn-ui-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node build/index.js --github-api-key YOUR_TOKEN

本地运行

# After building, run with options
node build/index.js --github-api-key YOUR_TOKEN
node build/index.js --framework svelte

构建 MCPB 软件包

项目包含符合 MCPB 规范的 manifest.json。.mcpb 文件是一个 ZIP 归档文件，包含服务、依赖项和配置。

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

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

🔗 快速链接

• 📖 完整文档
• 🚀 入门指南
• 🌐 HTTP 传输与 Docker 指南
• 🧭 现代协议指南（2026-07-28）
• 📝 更新日志
• 🎨 框架比较
• 🔧 API 参考
• 🐛 故障排除
• 💬 问题与讨论

📄 许可证

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

🙏 致谢

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

---

由 Janardhan Polle 倾情打造 ❤️

如果觉得这个仓库对你有帮助，请点亮 ⭐！