MCP 服务器

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

🌐 The shadcn MCP Server allows AI assistants to interact with items from registries. You can browse available components, search for specific ones, and install them directly into your project using natural language.

例如，你可以让AI助手“使用acme注册表的组件构建登陆页”或“从shadcn注册表中查找登录表单”。

🌐 For example, you can ask an AI assistant to "Build a landing page using components from the acme registry" or "Find me a login form from the shadcn registry".

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

🌐 Registries are configured in your project's components.json file.

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

快速开始

🌐 Quick Start

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

🌐 Select your MCP client and follow the instructions to configure the shadcn MCP server. If you'd like to do it manually, see the Configuration section.

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

什么是MCP？

🌐 What is MCP?

模型上下文协议 (MCP) 是一种开放协议，使 AI 助手能够安全地连接到外部数据源和工具。通过 shadcn MCP 服务器，你的 AI 助手可以直接访问：

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

运作方式

🌐 How It Works

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

🌐 The MCP server acts as a bridge between your AI assistant, component registries and the shadcn CLI.

1. 注册表连接 - MCP 连接到配置的注册表（shadcn/ui、私有注册表、第三方来源）
2. 自然语言 - 你用普通英语描述你需要的内容
3. 人工智能处理 - 助手将你的请求转换为注册表命令
4. 组件交付 - 资源会被获取并安装到你的项目中

支持的注册表

🌐 Supported Registries

shadcn MCP 服务器可以开箱即用，兼容任何 shadcn 兼容的注册表。

🌐 The shadcn MCP server works out of the box with any shadcn-compatible registry.

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

配置

🌐 Configuration

你可以使用任何 MCP 客户端与 shadcn MCP 服务器进行交互。以下是最受欢迎的客户端的使用说明。

🌐 You can use any MCP client to interact with the shadcn MCP server. Here are the instructions for the most popular ones.

Claude Code

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

🌐 To use the shadcn MCP server with Claude Code, add the following configuration to your project's .mcp.json file:

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

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

🌐 After adding the configuration, restart Claude Code and run /mcp to see the shadcn MCP server in the list. If you see Connected, you're good to go.

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

🌐 See the Claude Code MCP documentation for more details.

Cursor

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

🌐 To configure MCP in Cursor, add the shadcn server to your project's .cursor/mcp.json configuration file:

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

添加配置后，请在 Cursor 设置中启用 shadcn MCP 服务器。

🌐 After adding the configuration, enable the shadcn MCP server in Cursor Settings.

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

🌐 Once enabled, you should see a green dot next to the shadcn server in the MCP server list and a list of available tools.

有关详细信息，请参见 Cursor MCP 文档。

🌐 See the Cursor MCP documentation for more details.

VS Code

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

🌐 To configure MCP in VS Code with GitHub Copilot, add the shadcn server to your project's .vscode/mcp.json configuration file:

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

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

🌐 After adding the configuration, open .vscode/mcp.json and click Start next to the shadcn server.

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

🌐 See the VS Code MCP documentation for more details.

Codex

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

🌐 To configure MCP in Codex, add the shadcn server to ~/.codex/config.toml:

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

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

🌐 After adding the configuration, restart Codex to load the MCP server.

配置注册表

🌐 Configuring Registries

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

🌐 The MCP server supports multiple registries through your project's components.json configuration. This allows you to access components from various sources including private registries and third-party providers.

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

🌐 Configure additional registries in your components.json:

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

身份验证

🌐 Authentication

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

🌐 For private registries requiring authentication, set environment variables in your .env.local:

CopyREGISTRY_TOKEN=your_token_here
API_KEY=your_api_key_here

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

🌐 For more details on registry authentication, see the Authentication documentation.

示例提示

🌐 Example Prompts

一旦 MCP 服务器配置完成，你可以使用自然语言与注册表进行交互。尝试以下提示之一：

🌐 Once the MCP server is configured, you can use natural language to interact with registries. Try one of the following prompts:

浏览与搜索

🌐 Browse & Search

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

安装项目

🌐 Install Items

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

与命名空间一起工作

🌐 Work with Namespaces

• 显示来自 acme 注册表的组件
• 安装 @internal/auth-form
• 用来自Acme注册表的英雄部分、功能和客户评价部分为我构建一个登录页面

故障排除

🌐 Troubleshooting

MCP 无响应

🌐 MCP Not Responding

如果MCP服务器没有响应提示：

🌐 If the MCP server isn't responding to prompts:

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

注册表访问问题

🌐 Registry Access Issues

如果组件未从注册表加载：

🌐 If components aren't loading from registries:

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

安装失败

🌐 Installation Failures

如果组件安装失败：

🌐 If components fail to install:

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

无工具或提示

🌐 No Tools or Prompts

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

🌐 If you see the No tools or prompts message, try the following:

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

了解更多

🌐 Learn More

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