MCP 服务器

shadcn MCP 服务器允许 AI 助手与注册表中的项目交互。您可以浏览可用组件、搜索特定组件，并使用自然语言将它们直接安装到您的项目中。

例如，您可以让 AI 助手执行“使用 acme 注册表中的组件构建一个登录页”或“帮我找一个来自 shadcn 注册表的登录表单”。

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

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

快速开始

选择您的 MCP 客户端并按照指示配置 shadcn MCP 服务器。如果您想手动配置，参见配置部分。

pnpmnpmyarnbun
pnpm dlx shadcn@latest mcp init --client claude
Copy

什么是 MCP？

模型上下文协议 (Model Context Protocol, MCP) 是一个开放协议，允许 AI 助手安全连接外部数据源和工具。借助 shadcn MCP 服务器，您的 AI 助手可以直接访问：

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

工作原理

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

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

支持的注册表

shadcn MCP 服务器即开即用，支持所有 shadcn 兼容的注册表。

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

配置

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

Claude Code

要在 Claude Code 中使用 shadcn MCP 服务器，请将以下配置添加到项目的 .mcp.json 文件：

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

添加配置后，重启 Claude Code 并运行 /mcp，您就可以在列表中看到 shadcn MCP 服务器。如果显示 Connected，说明配置成功。

详见Claude Code MCP 文档。

Cursor

在 Cursor 中配置 MCP，请在项目的 .cursor/mcp.json 配置文件中添加 shadcn 服务器：

Copy{
  "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 配置文件：

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

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

详见VS Code MCP 文档。

Codex

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

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

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

配置注册表

MCP 服务器支持通过项目的 components.json 配置多个注册表。这样您可以访问包括私有注册表和第三方提供方在内的多种来源组件。

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

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

认证

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

CopyREGISTRY_TOKEN=your_token_here
API_KEY=your_api_key_here

更多关于注册表认证的详情，请参见认证文档。

示例提示语

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

浏览和搜索

• 显示 shadcn 注册表中所有可用组件
• 找一个来自 shadcn 注册表的登录表单

安装组件

• 将按钮组件添加到我的项目
• 使用 shadcn 组件创建登录表单
• 安装来自 acme 注册表的 Cursor 规则

使用命名空间

• 显示 acme 注册表的组件
• 安装 @internal/auth-form
• 用来自 acme 注册表的英雄区、特色区和客户评价区搭建一个登录页

故障排查

MCP 无响应

如果 MCP 服务器对提示无响应：

1. 检查配置 - 确认 MCP 服务器已正确配置并在 MCP 客户端中启用
2. 重启 MCP 客户端 - 配置改动后重启客户端
3. 确认安装 - 确保项目中已安装 shadcn
4. 检查网络 - 确认可以访问已配置的注册表

注册表访问问题

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

1. 检查 components.json - 确认注册表 URL 正确
2. 测试认证 - 确保私有注册表环境变量已设置
3. 确认注册表在线 - 注册表服务器可用且访问正常
4. 检查命名空间语法 - 确认使用正确的 @namespace/component 格式

安装失败

如果组件安装失败：

1. 检查项目设置 - 确保有有效的 components.json
2. 确认路径 - 目标目录存在
3. 检查权限 - 有写入组件目录的权限
4. 检查依赖 - 确保安装了所需依赖

显示“无工具或提示”

遇到 No tools or prompts 消息，请尝试：

1. 清理 npx 缓存 - 运行 npx clear-npx-cache
2. 重新启用 MCP 服务器 - 在 MCP 客户端中再启用一次 MCP 服务器
3. 查看日志 - 在 Cursor 中进入“视图 -> 输出”，从下拉菜单选择 MCP: project-* 查看日志

了解更多

• 注册表文档 - shadcn 注册表完整指南
• 命名空间 - 配置多个注册表源
• 认证 - 保护您的私有注册表
• MCP 规范 - 了解模型上下文协议