Skip to main content
Glama
heroui-v2-mcp
by dmjacas

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

工具

工具

用途

list_components

列出所有 v2 组件别名(匹配 v2.heroui.com/docs/components/<别名>)

get_component_docs

描述、安装命令、导入、使用指南、属性/API 表格

get_component_source_code

来自 packages/components/<包>/src 的 React/TypeScript 源代码

get_component_source_styles

来自 packages/core/theme/src/components 的 tailwind-variants 样式定义

get_docs

通用指南:安装、框架、主题、CLI、HeroUIProvider 等。

get_theme_variables

默认语义颜色 + 布局令牌

安装与运行

该包已发布到 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)。重启进程以强制提前刷新。

Available Tools

6 tools
get_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

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A high-quality, open-source Model Context Protocol (MCP) server that bridges AI systems and HeroUI, enabling intelligent assistance for developers working with HeroUI components.
      17
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Comprehensive 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.
      13
      21 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local, free MCP server for brand logo search and shadcn/ui component search & source lookup, requiring no API keys or login.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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