shadcn/ui 中文文档 | 构建你自己的组件库

使用 shadcn MCP 服务器来浏览、搜索和安装来自注册表（registries）的组件。

shadcn MCP Server 允许 AI 助手与注册表中的项目进行交互。您可以浏览可用组件、搜索特定组件，并通过自然语言直接将其安装到您的项目中。

例如，您可以向 AI 助手提问："使用 acme 注册表中的组件构建一个着陆页" 或 "帮我从 shadcn 注册表中找一个登录表单"。

注册表在项目的 components.json 文件中配置。

json
{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}

什么是 MCP？

Model Context Protocol (MCP) 是一个开放协议，使 AI 助手能够安全地连接到外部数据源和工具。使用 shadcn MCP 服务器，您的 AI 助手可以直接访问：

浏览组件 — 列出任何已配置注册表中的所有可用组件、blocks 和模板
跨注册表搜索 — 按名称或功能跨多个源查找特定组件
自然语言安装 — 使用简单的对话提示添加组件，如 "添加一个登录表单"
多注册表支持 — 访问公共注册表、私有公司库和第三方源

快速开始

选择您的 MCP 客户端并按照说明配置 shadcn MCP 服务器。如果您希望手动配置，请参阅配置部分。

Claude Code

在您的项目中运行以下命令：

bash
pnpm dlx shadcn@latest mcp init --client claude

重新启动 Claude Code 并尝试以下提示：

显示 shadcn 注册表中所有可用的组件
将 button、dialog 和 card 组件添加到我的项目中
使用 shadcn 注册表中的组件创建一个联系表单

注意： 您可以在 Claude Code 中使用 /mcp 命令来调试 MCP 服务器。

Cursor

要将 MCP 配置到 Cursor 中，将 shadcn 服务器添加到您的项目 .cursor/mcp.json 配置文件中：

json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

添加配置后，在 Cursor 设置中启用 shadcn MCP 服务器。启用后，您应该会在 MCP 服务器列表中看到 shadcn 服务器旁边出现一个绿色圆点，以及可用的工具列表。

有关更多详细信息，请参阅 Cursor MCP 文档。

VS Code

要在 VS Code 中使用 GitHub Copilot 配置 MCP，将 shadcn 服务器添加到您的项目 .vscode/mcp.json 配置文件中：

json
{
  "servers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

添加配置后，打开 .vscode/mcp.json 并点击 shadcn 服务器旁边的 Start。

有关更多详细信息，请参阅 VS Code MCP 文档。

Codex

注意： shadcn CLI 无法自动更新 ~/.codex/config.toml。您需要手动添加配置。

要将 MCP 配置到 Codex 中，将 shadcn 服务器添加到 ~/.codex/config.toml：

toml
[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]

添加配置后，重新启动 Codex 以加载 MCP 服务器。

工作原理

MCP 服务器充当您的 AI 助手、组件注册表和 shadcn CLI 之间的桥梁。

注册表连接 — MCP 连接到已配置的注册表（shadcn/ui、私有注册表、第三方源）
自然语言 — 您用自然语言描述您的需求
AI 处理 — 助手将您的请求转换为注册表命令
组件交付 — 资源被获取并安装到您的项目中

支持的注册表

shadcn MCP 服务器开箱即用，支持任何与 shadcn 兼容的注册表。

shadcn/ui 注册表 — 包含所有 shadcn/ui 组件的默认注册表
第三方注册表 — 任何遵循 shadcn 注册表规范的注册表
私有注册表 — 您公司的内部组件库
命名空间注册表 — 使用 @namespace 语法配置的多个注册表

配置

您可以使用任何 MCP 客户端与 shadcn MCP 服务器交互。以下是最流行客户端的配置说明。

手动配置（通用）

对于 Claude Code，将以下配置添加到项目根目录的 .mcp.json 文件：

json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

添加配置后，重新启动客户端。

配置注册表

MCP 服务器通过项目的 components.json 配置支持多个注册表。这允许您访问来自各种源的组件，包括私有注册表和第三方提供商。

在 components.json 中配置额外的注册表：

json
{
  "registries": {
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": {
      "url": "https://internal.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

注意： 访问标准的 shadcn/ui 注册表无需额外配置。

认证

对于需要认证的私有注册表，在 .env.local 中设置环境变量：

bash
REGISTRY_TOKEN=your_token_here
API_KEY=your_api_key_here

有关注册表认证的更多详细信息，请参阅认证文档。

示例提示词

配置好 MCP 服务器后，您可以使用自然语言与注册表交互。尝试以下提示词：

浏览与搜索

显示 shadcn 注册表中所有可用的组件
帮我从 shadcn 注册表中找一个登录表单

安装项目

将 button 组件添加到我的项目中
使用 shadcn 组件创建一个登录表单
从 acme 注册表安装 Cursor rules

使用命名空间

显示 acme 注册表中的组件
安装 @internal/auth-form
使用 acme 注册表中的 hero、features 和 testimonials 部分构建一个着陆页

故障排除

MCP 无响应

如果 MCP 服务器未响应提示：

检查配置 — 验证 MCP 服务器已正确配置并在 MCP 客户端中启用
重启 MCP 客户端 — 配置更改后重新启动 MCP 客户端
验证安装 — 确保项目中已安装 shadcn
检查网络 — 确认您可以访问已配置的注册表

注册表访问问题

如果组件无法从注册表加载：

检查 components.json — 验证注册表 URL 是否正确
测试认证 — 确保已为私有注册表设置环境变量
验证注册表 — 确认注册表在线且可访问
检查命名空间 — 确保命名空间语法正确（@namespace/component）

安装失败

如果组件安装失败：

检查项目设置 — 确保存在有效的 components.json 文件
验证路径 — 确认目标目录存在
检查权限 — 确保对组件目录有写入权限
检查依赖项 — 确认已安装所需的依赖项

无工具或提示

如果看到 No tools or prompts 消息，请尝试以下操作：

清除 npx 缓存 — 运行 npx clear-npx-cache
重新启用 MCP 服务器 — 在 MCP 客户端中尝试重新启用 MCP 服务器
检查日志 — 在 Cursor 中，可以在 View -> Output 下查看日志，并在下拉菜单中选择 MCP: project-*

了解更多

注册表文档 — shadcn 注册表的完整指南
命名空间 — 配置多个注册表源
认证 — 保护您的私有注册表
MCP 规范 — 了解 Model Context Protocol

MCP 服务器 (MCP Server)