21st-dev/magic-mcp · 上手攻略

仓库：21st-dev/magic-mcp
链接：https://github.com/21st-dev/magic-mcp
分类：MCP Server · UI Generation · AI Coding Agent
作者：Tom
更新：2026-07-25

是什么

21st-dev/magic-mcp 是 21st.dev 平台的 MCP（Model Context Protocol）服务器，专门为 AI 编程助手（Cursor、Windsurf、Claude Code、Cline、VS Code 等）提供 UI 组件生成能力。官方自称"like v0, but in your Cursor / Claude Code / Windsurf"——用自然语言描述一个 React 组件，Agent 就能在编辑器里生成对应代码。

该项目现已升级为统一的 21st MCP（Magic MCP v0.2.0+ 只是兼容代理层），安装方式也从独立的 @21st-dev/magic 包改为统一的 @21st-dev/cli。旧包名保留作为兼容代理，所有调用被转发到同一后端。

核心功能是 UI 组件生成：用自然语言描述想要的前端组件，AI 在编辑器中生成可运行的 React 代码，支持多变体（multiple variants）输出，方便对比选择最佳设计。

解决什么问题

在使用 Cursor/Windsurf 等 AI coding agent 时，想加一个 UI 组件通常需要：手动写组件代码、查文档、复制粘贴示例，流程碎片化。21st MCP 把 21st.dev 的设计工程师社区组件库直接接入 AI agent 的工具集，让 Agent 在对话中就能生成高质量 React 组件并注入到当前文件里，减少上下文切换。

解决的问题： 1. 组件从哪里来：21st.dev 社区有大量设计师工程师贡献的 React 组件，覆盖各类场景 2. 生成 vs 搜索：不只是从库中搜索，还可以根据描述生成新变体 3. 多 AI 客户端支持：一套 MCP 配置，同时支持 Cursor、Windsurf、Claude Code、Cline 等主流 coding agent

快速安装

方式一：CLI 初始化（推荐）

# 安装最新 CLI 并初始化，选择你的 AI 客户端
npx @21st-dev/cli@latest init --client cursor
# 或指定其他客户端
npx @21st-dev/cli@latest init --client claude
npx @21st-dev/cli@latest init --client vscode
npx @21st-dev/cli@latest init --client windsurf
npx @21st-dev/cli@latest init --client codex

CLI 会引导你完成 API key 配置和 MCP 连接。

方式二：手动配置 MCP（JSON）

在支持 MCP 的编辑器（Cursor、Windsurf 等）的 MCP 配置文件（通常是 .cursor/mcp.json、/.windsurf/mcp.json 等）中添加：

{
  "mcpServers": {
    "21st": {
      "url": "https://21st.dev/api/mcp",
      "headers": {
        "x-api-key": "YOUR_21ST_API_KEY"
      }
    }
  }
}

API Key 获取

访问 https://21st.dev/mcp
注册/登录账号
生成新的 API key（旧的 Magic MCP key 已全部重置，需要重新生成）
将 key 填入上述配置

方式三：旧包兼容模式（已不推荐）

npx -y @21st-dev/magic@latest API_KEY="your-key"
# 自 v0.2.0 起这只是转发层，实际调用 21st MCP 后端

核心用法

在 AI Agent 对话中生成组件

连接成功后，在 AI coding agent 的聊天窗口中：

/ui 一个紫色的渐变按钮，带 hover 效果，radius 12px

或者用新版自然语言指令：

生成一个侧边导航栏，包含 5 个菜单项，当前选中项高亮

⚠️ 旧的 /ui、/21 等触发短语已废弃，请使用自然语言描述需求。

主要工具（Tools）

工具名（新版）	工具名（旧版 Magic）	功能
`generate`	`21st_magic_component_builder`	根据描述生成 UI 组件
`get_inspiration`	`21st_magic_component_inspiration`	获取组件灵感/参考
`generate`（带 refinement）	`21st_magic_component_refiner`	基于已有组件做精调
`search_logo`	`logo_search`	搜索 logo 资源
`search`	—	搜索组件/主题/模板目录
`bookmarks`	—	管理个人收藏
`team_libaries`	—	团队组件库
`profile`	—	用户资料管理

⚠️ 旧工具名仍然被服务端兼容，但建议迁移到新版工具名。

变体生成（重要特性）

generate 每次调用会返回多个变体，不是只有一个结果。用户可以对比多个设计方案，选择最喜欢的一个继续精调。这是 21st MCP 区别于普通组件搜索的核心差异。

组件代码归属

生成的组件代码归属用户，21st.dev 提供设计参考和生成服务，代码本身无使用限制。

典型适用场景

场景	说明
Cursor/Windsurf AI 编程	在编辑器的 AI chat 里直接生成 React 组件代码
快速原型	用自然语言描述想要的前端，快速获得可运行代码
设计系统扩展	基于社区组件生成自己风格的新组件
多方案对比	一次生成多个 variant，便于产品/设计讨论
Claude Code 增强	为 Claude Code 补充 UI 生成能力（原本以代码为主）

坑与注意

API Key 必须重新生成：Magic MCP 时期的 key 已全部重置，无论旧 key 格式如何，必须到 https://21st.dev/mcp 生成新 key，旧 key 在任何地方都无法使用。
免费额度与付费：组件目录搜索基本可用，但代码检索（code retrieval）和部分高级功能可能需要付费 plan，具体计费模式需以官网为准。
仅支持 React：生成和搜索的组件均为 React 组件，不支持 Vue、Svelte 或其他框架。
依赖 21st.dev 在线服务：MCP 服务器是 HTTP 连接至 21st.dev/api/mcp，不是完全离线的——本地网络必须能访问 21st.dev。
工具调用限制：部分模型（如某些 Ollama 本地模型）可能不支持 MCP 工具调用格式，建议使用有官方工具调用支持的模型（GPT-4o、Claude 3.5 Sonnet、Gemini 等）。
安全审查：生成第三方依赖的代码建议在独立分支上测试后合并，不建议直接接受未经 review 的生成代码到主分支。
v0.2.0 兼容层是转发代理：@21st-dev/magic 包本身功能极其有限，实际能力取决于 21st MCP 后端，升级后端时兼容层不需要更新。

与同类对比

工具/服务	UI 生成方式	组件库规模	离线可用	适用框架	客户端支持
21st MCP	自然语言生成 + 社区搜索 + 多变体	21st.dev 设计师社区	❌（需联网）	React	Cursor/Windsurf/Claude Code/Cline
v0/Lovart	截图/描述生成	自有设计系统	❌	Web	Web App
Bolt.new / Bolt.diy	全栈生成	自有方案	❌	React（偏向全栈）	Web App
Cursor 内置	代码补完为主	无专门 UI 生成	✅（本地模型）	通用	Cursor
Cline	MCP 扩展支持	依赖 MCP server	取决于 server	通用	VS Code/Cline
本地 UI 生成（MCP）	各 MCP server 不同	各不相同	✅（完全本地）	多	取决于 server

核心差异：21st MCP 的优势是设计师社区贡献的组件质量和设计审美，变体生成让对比更高效；劣势是完全依赖线上服务和 React 生态。

一句话推荐结论

如果你已经用 Cursor/Windsurf/Claude Code 作为日常编程工具，想要在对话中直接生成高质量 React UI 组件而不用切换到 Figma 或组件库文档，21st MCP 是目前最顺滑的集成方案——前提是你能接受组件代码走第三方在线服务和 React 技术栈。

参考来源

GitHub 仓库：https://github.com/21st-dev/magic-mcp
21st MCP 官网：https://21st.dev/mcp
21st.dev AI 主页：https://21st.dev/ai
npm @21st-dev/cli：https://www.npmjs.com/package/@21st-dev/cli
Awesome MCP Servers（magic-mcp）：https://mcpservers.org/servers/21st-dev/magic-mcp
MCP.so 介绍页：https://mcp.so/servers/magic-mcp
AgentSkillsHub 评测：https://agentskillshub.dev/skills/21st-dev-magic