shadcn/ui MCP Server

什么是 shadcn/ui MCP Server？

shadcn/ui MCP Server 是一个社区开发的 shadcn MCP 服务器，可为 AI 助手提供 shadcn/ui v4 组件的源代码、示例、区块（blocks）和元数据，并支持 Svelte、Vue 和 React Native 移植版本。它是由 Janardhan Polle（Jpisnice）维护的非官方开源项目，采用 MIT 许可证。

该服务器从上游 GitHub 仓库读取组件代码，因此你的 AI 助手可以基于真实、最新的 shadcn ui MCP 源码编写界面，而不是凭训练数据猜测。它默认通过 stdio 在本地运行，也可以提供 Streamable HTTP 服务以支持多客户端部署。

如何使用 shadcn/ui MCP Server？

需要 Node.js 20 或更高版本。GitHub 个人访问令牌（personal access token）是可选的，但推荐配置：不使用令牌时，服务器每小时最多发起 60 次 GitHub API 请求；使用令牌后为 5,000 次。该令牌无需任何权限范围（scopes），可在 https://github.com/settings/tokens 创建，并通过 --github-api-key 参数或 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量传入。

直接用 npx 运行：

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

# Other 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

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

Claude Code

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

如果服务器以 HTTP 模式运行：

node build/index.js --mode http --port 7423
claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp

Claude Desktop

从项目的 GitHub Releases 下载 shadcn-ui-mcp-server.mcpb 并双击安装，或将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Cursor

打开 Cursor 设置，搜索 MCP，然后添加：

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

VS Code

运行 “MCP: Add Server...”，选择 “NPM Package”，并输入 @jpisnice/shadcn-ui-mcp-server。生成的 mcp.json 配置如下（可配合 Copilot Chat 使用）：

{
  "servers": {
    "shadcn-ui-mcp-server": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "react", "--ui-library", "radix"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" },
      "type": "stdio"
    }
  },
  "inputs": [
    { "id": "github_token", "type": "promptString", "description": "GitHub Personal Access Token" }
  ]
}

shadcn/ui MCP Server 的主要功能

• 支持四种框架：React（shadcn/ui v4，默认）、Svelte（shadcn-svelte）、Vue（shadcn-vue）和 React Native（react-native-reusables），通过 --framework 选择。
• React 可通过 --ui-library 或 UI_LIBRARY 选择 Radix UI 或 Base UI 原语。
• 提供组件源代码、示例代码以及依赖等元数据。
• 提供完整的区块实现，例如 dashboard-01 和 calendar-01。
• 支持列出、查看和应用 tweakcn 主题预设。
• 对 GitHub API 调用进行缓存并处理速率限制。
• 传输方式：stdio（默认）、http（位于 /mcp 的无状态 Streamable HTTP，默认端口 7423）和 dual；附带 Docker 和 Docker Compose 文件。
• 支持 Claude Desktop 一键安装 .mcpb。

shadcn/ui MCP Server 工具

• 组件工具： list_components 返回所有可用组件，get_component 返回组件源码，get_component_demo 返回示例用法，get_component_metadata 返回依赖和描述信息。
• 区块工具： list_blocks 按分类列出区块，get_block 返回某个区块（如 dashboard-01）的完整代码。
• 仓库工具： get_directory_structure 用于浏览上游仓库的目录结构。
• 主题工具： list_themes 和 get_theme 读取 tweakcn 主题；apply_theme 将主题预设的 CSS 写入你的项目，并支持 dryRun 选项。

shadcn/ui MCP Server 的使用场景

• 用真实组件构建功能：“Get the card component with usage examples and build a pricing card.”（获取 card 组件及示例，并构建一个定价卡片。）
• 基于区块搭建页面：“Get the dashboard-01 block implementation and adapt it to my analytics data.”（获取 dashboard-01 区块实现，并适配我的分析数据。）
• 发现组件：“List all available shadcn/ui components and suggest which to use for a settings page.”（列出所有可用的 shadcn/ui 组件，并推荐适合设置页面的组件。）
• 跨框架开发：“Compare the button component between React and Svelte”（比较 React 和 Svelte 中的 button 组件）或 “Show me the Vue version of the card component”（展示 card 组件的 Vue 版本）。
• 主题定制：先用 apply_theme 的 dry-run 模式预览 tweakcn 预设，再写入 CSS。
• 团队部署：在 Docker 中运行一个 HTTP 实例，让多个客户端连接 /mcp。

shadcn/ui MCP Server 与替代方案对比

shadcn 现已在其 CLI 中提供官方 shadcn MCP 服务器（文档）。它专注于 registry（组件注册表）：浏览、搜索并安装 components.json 中所配置 registry 的条目，可通过 npx shadcn@latest mcp init --client claude 配置（也支持 cursor、vscode、codex、opencode）。如果你主要想把 registry 组件安装到项目中，选择官方服务器；如果你需要原始组件和区块源码、示例、tweakcn 主题，或 Svelte、Vue、React Native 移植版本，选择这个社区版 shadcn mcp server。两者可以同时使用。

shadcn/ui MCP Server 常见问题排查

• 速率限制错误： 通过 --github-api-key 或 GITHUB_PERSONAL_ACCESS_TOKEN 添加 GitHub 令牌，可将限额从每小时 60 次提高到 5,000 次。
• 服务器无法启动： 检查 node --version（自 3.0.0 起需要 20 及以上版本）和 npx --version。
• 框架不对： 启动日志会显示当前框架，例如 INFO: MCP Server configured for SVELTE framework。日志输出到 stderr，请查看客户端的 MCP 日志。
• /sse 返回 404： 旧版 SSE 传输已被移除；请使用 http 传输连接 http://<host>:7423/mcp。
• -32022 Unsupported protocol version： 客户端使用 2025 年版本的协议，而服务器以 --protocol modern 运行；请使用 --protocol any（默认值）。