MCP Server

shadcn MCP Server 允许 AI 助手与 registry 中的项目交互。你可以浏览可用组件、搜索特定组件，并通过自然语言直接将它们安装到项目中。

例如，你可以让 AI 助手“使用 acme registry 中的组件构建一个落地页”，或者“帮我在 shadcn registry 中找一个登录表单”。

registry 在你的项目 components.json 文件中配置。

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

快速开始

选择你的 MCP 客户端，并按照说明配置 shadcn MCP server。如果你想手动配置，请查看 配置 部分。

pnpmnpmyarnbun
pnpm dlx shadcn@latest mcp init --client claude
复制

什么是 MCP？

Model Context Protocol (MCP) 是一种开放协议，它允许 AI 助手安全连接到外部数据源和工具。通过 shadcn MCP server，你的 AI 助手可以直接访问：

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

工作原理

MCP server 充当你的 AI 助手、组件 registry 与 shadcn CLI 之间的桥梁。

1. 连接 registry - MCP 连接到已配置的 registry（shadcn/ui、私有 registry、第三方来源）
2. 自然语言输入 - 你用自然语言描述你的需求
3. AI 处理 - 助手把你的请求翻译成 registry 命令
4. 组件交付 - 资源被获取并安装到你的项目中

支持的 Registry

shadcn MCP server 可直接与任何兼容 shadcn 的 registry 配合使用。

• shadcn/ui Registry - 默认 registry，包含所有 shadcn/ui 组件
• 第三方 Registry - 任何遵循 shadcn registry 规范的 registry
• 私有 Registry - 你公司的内部组件库
• 命名空间 Registry - 使用 @namespace 语法配置的多个 registry

配置

你可以使用任何 MCP 客户端与 shadcn MCP server 交互。以下是最常见客户端的配置说明。

Claude Code

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

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

添加配置后，重启 Claude Code 并运行 /mcp，在列表中查看 shadcn MCP server。如果看到 Connected，就可以开始使用了。

更多细节请参阅 Claude Code MCP 文档。

Cursor

要在 Cursor 中配置 MCP，请将 shadcn server 添加到你项目的 .cursor/mcp.json 配置文件中：

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

添加配置后，在 Cursor Settings 中启用 shadcn MCP server。

启用后，你应该会在 MCP server 列表中看到 shadcn server 旁边的绿色圆点，以及可用工具列表。

更多细节请参阅 Cursor MCP 文档。

VS Code

要在 VS Code 中通过 GitHub Copilot 配置 MCP，请将 shadcn server 添加到你项目的 .vscode/mcp.json 配置文件中：

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

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

更多细节请参阅 VS Code MCP 文档。

Codex

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

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

添加配置后，重启 Codex 以加载 MCP server。

配置 Registries

MCP server 通过你项目的 components.json 配置支持多个 registry。这让你可以访问来自私有 registry 和第三方提供方等不同来源的组件。

在你的 components.json 中配置额外的 registry：

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

认证

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

CopyREGISTRY_TOKEN=your_token_here
API_KEY=your_api_key_here

有关 registry 认证的更多细节，请参阅 认证文档。

示例提示

配置好 MCP server 后，你就可以用自然语言与 registry 交互。可以试试下面这些提示：

浏览与搜索

• 显示 shadcn registry 中所有可用的组件
• 在 shadcn registry 中帮我找一个登录表单

安装项目

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

使用命名空间

• 显示 acme registry 中的组件
• 安装 @internal/auth-form
• 使用 acme registry 中的 hero、features 和 testimonials 区块为我构建一个落地页

故障排查

MCP 没有响应

如果 MCP server 对提示没有响应：

1. 检查配置 - 确认 MCP server 已正确配置并在你的 MCP 客户端中启用
2. 重启 MCP 客户端 - 在修改配置后重启你的 MCP 客户端
3. 确认安装 - 确保你的项目中已安装 shadcn
4. 检查网络 - 确认你可以访问已配置的 registries

Registry 访问问题

如果组件无法从 registry 加载：

1. 检查 components.json - 确认 registry URL 正确
2. 测试认证 - 确认私有 registry 的环境变量已设置
3. 验证 registry - 确认 registry 在线且可访问
4. 检查命名空间 - 确认命名空间语法正确（@namespace/component）

安装失败

如果组件安装失败：

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

没有工具或提示

如果你看到 No tools or prompts 消息，请尝试以下方法：

1. 清理 npx 缓存 - 运行 npx clear-npx-cache
2. 重新启用 MCP server - 尝试在你的 MCP 客户端中重新启用 MCP server
3. 查看日志 - 在 Cursor 中，你可以在 View -> Output 下拉菜单里选择 MCP: project-* 查看日志。

了解更多

• Registry 文档 - shadcn registries 完整指南
• Namespaces - 配置多个 registry 来源
• Authentication - 为你的私有 registry 提供安全保护
• MCP Specification - 了解 Model Context Protocol