heroui-v2-mcp

MCP (Model Context Protocol) server for HeroUI v2 (https://v2.heroui.com) component documentation, source code, style definitions and theme tokens.

Unlike the official @heroui/react-mcp — which targets HeroUI v3 and needs a deployed Cloudflare Worker + R2 bucket + PostHog project behind it — this is a standalone local server: it fetches everything on demand directly from heroui-inc/heroui@main (the branch that tracks v2.x) and raw.githubusercontent.com, caching results in memory for the life of the process. No cloud account, API deployment or extraction pipeline required.

Why a separate project

HeroUI v3 (branch v3, site heroui.com) and v2 (branch main, site v2.heroui.com) are different, incompatible component models — different package layout, no llms.txt on the v2 site, different docs folder structure (/docs/components/* vs /docs/react/*), different styling approach (tailwind-variants files under packages/core/theme/src/components vs whatever v3 uses). The official MCP explicitly refuses to serve v2 docs, so this project mirrors its tool surface but points at the v2 data sources.

Tools

| Tool | Purpose | | --- | --- | | list_components | List all v2 component slugs (matches v2.heroui.com/docs/components/<slug>) | | get_component_docs | Description, install command, imports, usage guidance, props/API table | | get_component_source_code | React/TypeScript source from packages/components/<pkg>/src | | get_component_source_styles | tailwind-variants style definition from packages/core/theme/src/components | | get_docs | General guides: installation, frameworks, theming, CLI, HeroUIProvider, etc. | | get_theme_variables | Default semantic colors + layout tokens |

Install & run

The package is published on npm as heroui-v2-mcp, so no clone or build step is required to use it.

Use from Claude Code / Claude Desktop / Cursor

Add to your MCP config — npx downloads and runs it on demand:

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

Or install it globally and point at the binary directly:

npm install -g heroui-v2-mcp

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

Local development (from source)

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 rate limits

Directory listings go through the GitHub REST API, which is capped at 60 requests/hour unauthenticated. File contents (raw.githubusercontent.com) are not subject to that limit. If you hit 403s while browsing many components, set a token:

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

How data is resolved

• Component list = files under apps/docs/content/docs/components/*.mdx on the main branch.
• Most doc slugs map 1:1 to a packages/components/<slug> package. A handful of doc pages document sub-components bundled into another package (e.g. textarea ships inside @heroui/input, checkbox-group inside @heroui/checkbox) — see COMPONENT_PACKAGE_ALIASES in src/constants.ts.
• Props/API tables are parsed out of the <APITable data={[...]} /> JSX literal embedded in each .mdx doc page (that array is evaluated as a JS literal — it's static data from the official repo, not arbitrary/untrusted input).
• Theme tokens come from packages/core/theme/src/colors/{semantic,common}.ts and default-layout.ts.

Caching

Every GitHub response (file content or directory listing) is cached in-memory for 30 minutes (CACHE_TTL_MS in src/constants.ts). Restart the process to force a refresh sooner.