如何把 HeroUI MCP Server 接入 Cursor、Claude Code 等编辑器并验证连接状态
如何把 HeroUI MCP Server 接入 Cursor、Claude Code 等编辑器并验证连接状态
HeroUI(原名 NextUI)提供 HeroUI MCP Server,让编辑器里的 AI 助手直接读取 HeroUI v3 的组件文档、源码和主题变量,这样你在用 Cursor、Claude Code 等 AI 开发环境写 HeroUI 代码时,助手拿到的就是官方的组件文档而不是猜测。这篇文章给出把 @heroui/react-mcp 接入各编辑器的配置方式和连接状态的验证方法。
HeroUI MCP Server 的关键前提,接入前先确认:
- 仅支持 @heroui/react v3,传输方式仅支持 stdio,包名为 npm 上的
@heroui/react-mcp; - 需要 Node.js 22 或更高版本,使用
npx时包会自动下载,无需手动安装; - 官方说明:随着更多组件加入 HeroUI v3,它们也会同步出现在 MCP Server 中。
各编辑器的配置差异只在「配置文件放在哪、字段名怎么写」,启动命令都是同一条:
npx -y @heroui/react-mcp@latest
接入 Claude Code
在终端运行:
claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
或者手动在项目根目录的 .mcp.json 中加入:
{
"mcpServers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
两种方式等价,选一种即可。
接入 Cursor
方式一:打开 Cursor Settings → Tools → MCP Servers,按官方文档站点提供的 Cursor 一键安装入口添加。
方式二:把下面这段加入项目中的 .cursor/mcp.json,或加入用户级 ~/.cursor/mcp.json:
{
"mcpServers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
官方文档没有为 Cursor 单独给出连接状态检查步骤,接入后可以直接用「验证连接状态」一节的通用方法确认。
接入 VS Code、Windsurf、Zed、Codex、OpenCode
以下是文档给出的其余编辑器配置,按需选用。
VS Code(配合 GitHub Copilot)
在项目中的 .vscode/mcp.json 添加:
{
"servers": {
"heroui-react": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
添加后打开 .vscode/mcp.json,点击 heroui-react 服务器旁的 Start 启动它。
Windsurf
在项目中的 .windsurf/mcp.json 添加:
{
"mcpServers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
添加配置后重启 Windsurf 即可激活 MCP Server。
Zed
通过 Command Palette(zed: open settings)或 Cmd-,(Mac)/ Ctrl-,(Linux)打开 settings.json,添加:
{
"context_servers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"],
"env": {}
}
}
}
Codex
添加到 ~/.codex/config.toml(用户级)或项目作用域的 .codex/config.toml:
[mcp_servers.heroui-react]
command = "npx"
args = ["-y", "@heroui/react-mcp@latest"]
OpenCode
添加到项目中的 opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"heroui-react": {
"type": "local",
"command": ["npx", "-y", "@heroui/react-mcp@latest"]
}
}
}
添加配置后重启 OpenCode 即可激活 MCP Server。
验证连接状态
各编辑器确认接入成功的方法如下,均以官方文档给出的判断为准:
| 编辑器 | 验证操作 | 成功现象 |
|---|---|---|
| Claude Code | 添加配置后重启 Claude Code,运行 /mcp |
列表中能看到 HeroUI MCP Server,状态显示 Connected |
| Codex | 重启 Codex,在 TUI 中运行 /mcp |
服务器处于 active 状态 |
| VS Code | 打开 .vscode/mcp.json,点击 heroui-react 旁的 Start |
服务器被启动 |
| Zed | 重启 Zed,打开 Agent Panel 的 settings 视图 | heroui 服务器旁的指示点为绿色,tooltip 显示 "Server is active" |
| Windsurf / OpenCode | 重启编辑器 | 文档仅说明重启后服务器被激活,未给出独立的状态指示 |
除界面状态外,最直接的判断方式是向 AI 助手提一个依赖文档的问题,例如:
- "Show me all HeroUI components"
- "What props does the Button component have?"
能正常列出组件、回答 props 细节,说明文档通道已经打通。
接入后可以做什么
接入成功后,MCP Server 向 AI 助手暴露以下工具:
| 工具 | 说明 |
|---|---|
list_components |
列出所有可用的 HeroUI v3 组件 |
get_component_docs |
获取一个或多个组件的完整文档,包括结构、props、示例和使用模式 |
get_component_source_code |
获取组件的 React/TypeScript 源码(.tsx 文件) |
get_component_source_styles |
查看组件的 CSS 样式(.css 文件) |
get_theme_variables |
获取颜色、排版、间距等主题变量,支持亮色/暗色模式 |
get_docs |
浏览完整的 HeroUI v3 文档,包括指南和原则(安装说明使用路径 /docs/react/getting-started/quick-start) |
文档给出的典型提问示例:
- "Help me install HeroUI v3 in my Next.js/Vite/Astro app"
- "Give me an example of using the Card component"
- "Get the source code for the Button component"
- "What are the theme variables for dark mode?"
此外,MCP Server 还支持让 AI 助手执行版本升级:对助手说 "Hey Cursor, update HeroUI to the latest version",助手会自动比对当前版本与最新 release、检查 changelog 中的破坏性变更,并应用必要的代码更新。该流程适用于任何版本升级,无论是升到最新稳定版还是预发布版。
限制与排查
- 文档给出的明确要求是 Node.js 22 或更高版本;如果
npx启动失败,先确认 Node 版本。 - 该 Server 仅支持 stdio 传输和 @heroui/react v3,不适用于 v2 项目。
- 需要帮助时可参考项目的 GitHub Issues 与 Discord 社区(入口见 MCP Server 文档/mcp-server.mdx) 的 Links 小节)。
注意区分:HeroUI 还单独提供了一个用于 v2 到 v3 迁移的 HeroUI Migration MCP Server,它使用 Streamable HTTP(URL)方式接入,配置和工具都与本文的 HeroUI MCP Server 不同,迁移完成后再切回本文的 Server 做 v3 组件开发。其配置方式见 迁移 MCP Server 文档/mcp-server.mdx)。