使用说明

Shadcn UI v4 MCP服务器

一种模型上下文协议（MCP）服务器，为人工智能助手提供全面的访问权限 shadcn/ui v4 组件、块、演示和元数据。该服务器使Claude Desktop、Continue.dev、VS Code、Cursor和其他MCP兼容客户端等AI工具能够无缝检索和使用shadcn/ui组件。

🚀 主要特点

组件源代码：获取最新的shadcn/ui v4组件TypeScript源代码
组件演示：访问示例实现和使用模式
块支持：检索完整的块实现（仪表板、日历、登录表单等）
元数据访问：获取组件依赖关系、描述和配置详细信息
目录浏览：探索shadcn/ui存储库结构
GitHub API集成：高效缓存和智能速率限制处理
框架支持：在React（shadcn/ui）、Vue（shadcn-Vue）或Svelte（shadcn Svelte）实现之间切换

📦 快速开始

⚡ 使用npx（推荐）

最快的入门方式-无需安装！

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

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

# Short form
npx @jpisnice/shadcn-ui-mcp-server -g ghp_your_token_here

# Using environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @jpisnice/shadcn-ui-mcp-server

# Switch to Svelte framework (default is react)
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Use Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here

# Switch to Vue framework with GitHub token (default is react)
npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key ghp_your_token_here
# Using environment variable for framework
export FRAMEWORK=svelte
npx @jpisnice/shadcn-ui-mcp-server

# Or use Vue
export FRAMEWORK=vue
npx @jpisnice/shadcn-ui-mcp-server

🎯 现在试试：运行 npx @jpisnice/shadcn-ui-mcp-server --help 查看所有选项！

🔄 框架选择：服务器支持React（shadcn/ui）、Svelte（shadcn-Svelte）和Vue（shadcn-Vue）实现。使用 --framework svelte 或 --framework vue 切换框架。

🔧 命令行选项

shadcn-ui-mcp-server [options]

Options:
  --github-api-key, -g <token>    GitHub Personal Access Token
  --framework, -f <framework>     Framework to use: 'react', 'svelte' or 'vue' (default: react)
  --help, -h                      Show help message
  --version, -v                   Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN    Alternative way to provide GitHub token
  FRAMEWORK                       Framework to use: 'react', 'svelte' or 'vue' (default: react)

Examples:
  npx @jpisnice/shadcn-ui-mcp-server --help
  npx @jpisnice/shadcn-ui-mcp-server --version
  npx @jpisnice/shadcn-ui-mcp-server -g ghp_1234567890abcdef
  GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token npx @jpisnice/shadcn-ui-mcp-server
  npx @jpisnice/shadcn-ui-mcp-server --framework svelte
  npx @jpisnice/shadcn-ui-mcp-server -f react
  export FRAMEWORK=svelte && npx @jpisnice/shadcn-ui-mcp-server

🔑 GitHub API令牌设置

你为什么需要代币？

无令牌：每小时限制为60个API请求
带令牌：每小时最多5000个请求
更高的可靠性和更快的响应速度

📝 获取代币（2分钟）

转到GitHub设置:
- 访问 GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
- 或者：GitHub个人资料→ 设置→ 开发人员设置→ 个人访问令牌
生成新令牌:
- 点击“生成新令牌（经典）”
- 添加注释：“shadcn-ui MCP服务器”
- 过期：选择您的偏好（建议90天）
- 范围: ✅ 不需要示波器！ （公共存储库访问权限就足够了）
复制您的令牌:
- 复制生成的令牌（以开头 ghp_)
- ⚠️ 安全保存 -你不会再看到它了！

🚀 使用您的令牌

方法1：命令行（快速测试）

npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

方法2：环境变量（推荐）

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Then simply run:
npx @jpisnice/shadcn-ui-mcp-server

🔄 框架选择

MCP服务器同时支持这两种功能反应（shadcn/ui）和 斯维尔特 （shadcn-svelte）实现。您可以根据项目需求在它们之间切换。

📋 框架比较

框架	存储库	文件扩展名	描述
反应（默认）	`shadcn-ui/ui`	`.tsx`	来自shadcn/ui v4的React组件
斯维尔特	`huntabyte/shadcn-svelte`	`.svelte`	来自shadcn Svelte的Svelte组件
视图	`unovue/shadcn-vue`	`.vue`	ShadCN的Vue组件-Vue

🎯 如何切换框架

方法1：命令行参数（推荐）

# Use React (default)
npx @jpisnice/shadcn-ui-mcp-server

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

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

# Switch back to React
npx @jpisnice/shadcn-ui-mcp-server --framework react
npx @jpisnice/shadcn-ui-mcp-server -f react

方法2：环境变量

# Use Svelte
export FRAMEWORK=svelte
npx @jpisnice/shadcn-ui-mcp-server

# Use React
export FRAMEWORK=react
npx @jpisnice/shadcn-ui-mcp-server

# Use Vue
export FRAMEWORK=vue
npx @jpisnice/shadcn-ui-mcp-server

# Or set for single command
FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server
FRAMEWORK=vue npx @jpisnice/shadcn-ui-mcp-server

方法三：结合GitHub Token

# Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here

# React with GitHub token (default)
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# Vue with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key ghp_your_token_here

🔍 框架检测

服务器将记录正在使用的框架：

INFO: Framework set to 'svelte' via command line argument
INFO: MCP Server configured for SVELTE framework
INFO: Repository: huntabyte/shadcn-svelte
INFO: File extension: .svelte

INFO: Framework set to 'vue' via command line argument
INFO: MCP Server configured for VUE framework
INFO: Repository: unovue/shadcn-vue
INFO: File extension: .vue

⚠️ 重要：使用环境变量时，请确保使用正确的语法：

✅ 对的： export FRAMEWORK=svelte && npx @jpisnice/shadcn-ui-mcp-server
✅ 对的： FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server
❌ 不正确： FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server （没有适当的间距）

💡 用例

React项目：使用默认值或 --framework react 用于React/Next.js应用程序
Svelte项目：使用 --framework svelte 用于Svelte/SvelteKit应用程序
项目视图：使用 --framework vue 用于Vue/Nuxt应用程序
多框架开发：在框架之间切换以比较实现
学习：探索相同组件的React、Svelte和Vue版本

🛠️ 编辑器集成

VS代码集成

方法1：使用Continue扩展

安装继续扩展:
- 打开VS代码
- 转到扩展（Ctrl+Shift+X）
- 搜索“继续”并安装
配置MCP服务器:
- 打开命令面板（Ctrl+Shift+P）
- 键入“继续：配置”并选择它
- 将此配置添加到您的设置中：

{
  "continue.server": {
    "mcpServers": {
      "shadcn-ui": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      },
      // If using Svelte, do this instead:
      "shadcn-ui-svelte": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--framework",
          "svelte",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      },
      // If using Vue, do this instead:
      "shadcn-ui-vue": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--framework",
          "vue",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      }
    }
  }
}

方法2：使用Claude扩展

安装Claude扩展:
- 在VS代码扩展中搜索“Claude”
- 安装官方的Claude扩展
配置MCP服务器:
- 添加到您的VS代码设置.json：

{
  "claude.mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "vue"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

光标集成

方法1：全局配置

打开光标设置:
- 转到设置（Cmd/Ctrl+，）
- 搜索“MCP”或“模型上下文协议”
添加MCP服务器配置:

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "svelte",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "vue",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

方法2：工作空间配置

创建一个 .cursorrules 项目根目录中的文件：

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "vue"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

克劳德代码（终端）集成

对于Claude Code终端用户，可以直接添加MCP服务器：

# Add the shadcn-ui MCP server with GitHub token
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_API_KEY

Claude桌面集成

添加到您的Claude Desktop配置(~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "svelte",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "vue",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

或者使用环境变量：

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

持续开发集成

安装Continue.dev:
- 下载自 continue.dev
- 安装应用程序
配置MCP服务器:
- 打开Continue.dev
- 转到“设置”→ MCP服务器
- 添加新服务器：

{
  "name": "shadcn-ui",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

对于瑞典人：

{
  "name": "shadcn-ui-svelte",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--framework",
    "svelte",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

或者对于Vue：

{
  "name": "shadcn-ui-vue",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--framework",
    "vue",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

🎯 使用示例

获取组件源代码

问你的AI助手：


"Show me the source code for the shadcn/ui button component"

AI现在可以访问按钮组件的完整TypeScript源代码。

创建仪表板

问你的AI助手：


"Create a dashboard using shadcn/ui components. Use the dashboard-01 block as a starting point"

AI可以检索完整的仪表板块实现，并根据您的需求进行定制。

构建登录表单

问你的AI助手：


"Help me build a login form using shadcn/ui components. Show me the available form components"

AI可以列出所有可用的组件，并帮助您构建表单。

🛠️ 可用工具

MCP服务器为AI助手提供以下工具：

组件工具

get_component -获取组件源代码
get_component_demo -获取组件使用示例
list_components -列出所有可用组件
get_component_metadata -获取组件依赖关系和信息

块工具

get_block -获取完整的块实现（仪表板-01、日历-01等）
list_blocks -按类别列出所有可用块

存储库工具

get_directory_structure -探索shadcn/ui存储库结构

工具使用示例

// These tools can be called by AI assistants via MCP protocol

// Get button component source
{
  "tool": "get_component",
  "arguments": { "componentName": "button" }
}

// List all components
{
  "tool": "list_components",
  "arguments": {}
}

// Get dashboard block
{
  "tool": "get_block",
  "arguments": { "blockName": "dashboard-01" }
}

🐛 故障排除

常见问题

“超出速率限制”错误：

# Solution: Add GitHub API token
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

“找不到命令”错误：

# Solution: Install Node.js 18+ and ensure npx is available
node --version  # Should be 18+
npx --version   # Should work

未找到组件：

# Check available components first
npx @jpisnice/shadcn-ui-mcp-server
# Then call list_components tool via your MCP client

网络/代理问题：

# Set proxy if needed
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
npx @jpisnice/shadcn-ui-mcp-server

编辑器无法识别MCP服务器：

# Verify the server is running
npx @jpisnice/shadcn-ui-mcp-server --help

# Check your editor's MCP configuration
# Ensure the command and args are correct

调试模式

启用详细日志记录：

# Set debug environment variable
DEBUG=* npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📞 支持

🐛 报告问题
💬 讨论
📖 文档
📦 npm包

🔗 相关项目

shadcn/ui -React组件库（默认框架）
shadcn 快速 -Svelte组件库
shadcn-视图 -Vue组件库
模型上下文协议 -协议规范
MCP TypeScript SDK -官方MCP SDK

⭐ 致谢

影电令人惊叹的UI组件库
Anthropic 用于模型上下文协议规范
开源社区的灵感和贡献

由以下材料制成❤️ 靠近 Janardhan Polle

星⭐ 如果你觉得这个仓库有用的话！

使用说明

Shadcn UI v4 MCP服务器

🚀 主要特点

📦 快速开始

⚡ 使用npx（推荐）

🔧 命令行选项

🔑 GitHub API令牌设置

📝 获取代币（2分钟）

🚀 使用您的令牌

🔄 框架选择

📋 框架比较

🎯 如何切换框架

🔍 框架检测

💡 用例

🛠️ 编辑器集成

VS代码集成

方法1：使用Continue扩展

方法2：使用Claude扩展

光标集成

方法1：全局配置

方法2：工作空间配置

克劳德代码（终端）集成

Claude桌面集成

持续开发集成

🎯 使用示例

获取组件源代码

创建仪表板

构建登录表单

🛠️ 可用工具

组件工具

块工具

存储库工具

工具使用示例

🐛 故障排除

常见问题

调试模式

📄 许可证

🤝 贡献

📞 支持

🔗 相关项目

⭐ 致谢

相关 MCP

代码索引分析工具

漏洞扫描服务

JADX APK逆向分析MCP插件

规范工作流管理工具

代码库打包工具

AI编码记忆系统