如何把 HeroUI MCP Server 接入 Cursor、Claude Code 等编辑器并验证连接状态

原创2026-09-11 21:28:391,685 阅读
文章标签:前端UI组件设计系统开源治理

如何把 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)。

登录后查看全文
nextui