heroui-v2-mcp
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
工具
工具 | 用途 |
| 列出所有 v2 组件别名(匹配 |
| 描述、安装命令、导入、使用指南、属性/API 表格 |
| 来自 |
| 来自 |
| 通用指南:安装、框架、主题、CLI、HeroUIProvider 等。 |
| 默认语义颜色 + 布局令牌 |
安装与运行
该包已发布到 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.jsGitHub 速率限制
目录列表通过 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)。重启进程以强制提前刷新。
Available Tools
6 toolsget_component_docsA
Get the full HeroUI v2 documentation for a single component: description, install command, import statements, usage guidance and the props/API reference table. Use list_components first to get valid slugs (e.g. "button", "date-range-picker").
Inputs: component (required).
get_component_source_codeA
Get the React/TypeScript source implementation of a HeroUI v2 component from packages/components//src on GitHub. Useful for understanding internals, hooks and ARIA wiring. Do NOT copy this directly — import the component from @heroui/react or its individual package instead. Use list_components first to get a valid slug.
Inputs: component (required).
get_component_source_stylesA
Get the default tailwind-variants style definition for a HeroUI v2 component, from packages/core/theme/src/components on GitHub. HeroUI v2 has no separate CSS files — every component's slots/variants/compoundVariants are defined as a tailwind-variants ("tv") object in TypeScript. Use this to see which classes back each variant/color/size, useful when writing custom classNames or a custom theme. Use list_components first to get a valid slug.
Inputs: component (required).
get_docsA
Get general HeroUI v2 documentation (guides, customization, frameworks, API references) — NOT component docs. Fetches MDX content from heroui-inc/heroui@main (apps/docs/content/docs). For component documentation use get_component_docs instead. Example paths: guide/introduction, guide/installation, guide/cli, guide/tailwind-v4, guide/nextui-to-heroui.
Inputs: path (required).
get_theme_variablesA
Get HeroUI v2's default theme tokens: semantic colors (light/dark) and layout tokens (radius, border widths, opacity, font sizes, box shadows). Source: heroui-inc/heroui@main, packages/core/theme. Use get_docs({ path: "customization/theme" }) or get_docs({ path: "customization/colors" }) for the narrative guide on overriding these via tailwind.config / createTheme.
Inputs: no named parameters.
list_componentsA
List all HeroUI v2 components (from v2.heroui.com / heroui-inc/heroui@main). This MCP only covers HeroUI v2 — it does NOT know about HeroUI v3 (https://heroui.com, "v3" branch). Always call this first to get the exact slug to pass to get_component_docs / get_component_source_code / get_component_source_styles. Slugs are the same as the path segment in https://v2.heroui.com/docs/components/.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct purpose: component docs, source code, styles, general docs, theme tokens, and component listing. No overlap exists, and descriptions clarify boundaries (e.g., get_docs explicitly excludes component docs).
All tool names follow a consistent verb_noun pattern (get_component_docs, get_component_source_code, get_component_source_styles, get_docs, get_theme_variables, list_components). The verb 'get' or 'list' is consistently used, and nouns clearly describe the resource.
With 6 tools, the set is well-scoped for a documentation and source code MCP server. Each tool addresses a specific need (docs, source, styles, general docs, theme, component listing) without unnecessary bloat or missing essentials.
The tool surface covers core documentation retrieval (component docs, source code, styles, general docs, theme variables) and component listing. A minor gap is the lack of a tool to search or filter components, but the core lifecycle for accessing HeroUI v2 information is fairly complete.
Maintenance
Related MCP Connectors
MCP server for StyleKit styles, tokens, recipes, lint and repair over stdio or HTTP.
MCP server for innovationlab documentation, generated by doc2mcp.
Read-only MCP server over the developer docs for the portfolio's JSON API, MCP, A2A and NLWeb.
MCP server for accessing curated awesome list documentation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA high-quality, open-source Model Context Protocol (MCP) server that bridges AI systems and HeroUI, enabling intelligent assistance for developers working with HeroUI components.17MIT
- AlicenseAqualityFmaintenanceComprehensive MCP server for end-to-end UI development, offering tools to generate components, manage design tokens, audit accessibility, autofix issues, inspect live pages, compare screenshots, and more across multiple frameworks.1321 npmMIT
- AlicenseNot gradedqualityDmaintenanceLocal, free MCP server for brand logo search and shadcn/ui component search & source lookup, requiring no API keys or login.MIT
- AlicenseNot gradedqualityCmaintenanceA local MCP server that lets MCP clients inspect and edit the Figma document currently open in the Figma desktop app using a local bridge and development plugin.MIT