heroui-v2-mcp

面向 HeroUI v2（https://v2.heroui.com）组件文档、源代码、样式定义和主题令牌的 MCP（模型上下文协议）服务器。

与官方 @heroui/react-mcp 不同——后者针对 HeroUI v3，且需要部署 Cloudflare Worker + R2 存储桶 + PostHog 项目——这是一个独立的本地服务器：它按需直接从 heroui-inc/heroui@main（跟踪 v2.x 的分支）和 raw.githubusercontent.com 获取所有内容，并在进程生命周期内将结果缓存到内存中。无需云账户、API 部署或提取流水线。

为什么是独立项目

HeroUI v3（分支 v3，站点 heroui.com）和 v2（分支 main，站点 v2.heroui.com）是不同的、不兼容的组件模型——包布局不同，v2 站点没有 llms.txt，文档文件夹结构不同（/docs/components/* 对比 /docs/react/*），样式方法不同（packages/core/theme/src/components 下的 tailwind-variants 文件对比 v3 使用的任何内容）。官方 MCP 明确拒绝提供 v2 文档，因此本项目镜像了其工具界面，但指向 v2 数据源。

Related MCP server: UI Toolkit MCP Server

工具

安装与运行

该包已发布到 npm，名称为 heroui-v2-mcp，因此无需克隆或构建步骤即可使用。

在 Claude Code / Claude Desktop / Cursor 中使用

添加到你的 MCP 配置中——npx 会按需下载并运行：

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

或全局安装并直接指向二进制文件：

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

本地开发（从源码）

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

GitHub 速率限制

目录列表通过 GitHub REST API 获取，未经身份验证时上限为 60 次请求/小时。文件内容（raw.githubusercontent.com）不受此限制。如果在浏览大量组件时遇到 403 错误，请设置一个令牌：

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

数据解析方式

• 组件列表 = main 分支下 apps/docs/content/docs/components/*.mdx 文件。

• 大多数文档别名与 packages/components/<别名> 包一一对应。少数文档页面记录的是打包在另一个包中的子组件（例如 textarea 位于 @heroui/input 内，checkbox-group 位于 @heroui/checkbox 内）——请参阅 src/constants.ts 中的 COMPONENT_PACKAGE_ALIASES。

• 属性/API 表格是从每个 .mdx 文档页面中嵌入的 <APITable data={[...]} /> JSX 字面量中解析出来的（该数组作为 JS 字面量求值——它是来自官方仓库的静态数据，而非任意/不可信的输入）。

• 主题令牌来自 packages/core/theme/src/colors/{semantic,common}.ts 和 default-layout.ts。

缓存

每个 GitHub 响应（文件内容或目录列表）都会在内存中缓存 30 分钟（src/constants.ts 中的 CACHE_TTL_MS）。重启进程以强制提前刷新。