HeroUI MCP

What is HeroUI MCP?

HeroUI MCP supplies on‑demand component documentation, props definitions, example usage, and theme information for the HeroUI design system. Two separate servers serve the web (React) and native (React Native) packages, keeping the data synchronized with the latest releases.

How to use HeroUI MCP?

Web (React/Next.js)

npx -y @heroui/react-mcp@latest

React Native

npx -y @heroui/native-mcp@latest

Run the appropriate command in a terminal; the server starts a local API (default ports 8787 for React and 8788 for Native). Integrate the endpoint in your AI assistant or tooling to query component metadata.

Key Features

• Component discovery with search and browsing
• Complete documentation: props, types, usage examples
• Theme data access: design tokens, color palettes, spacing
• Source code viewing for implementation details
• Automatic updates – data regenerated on each release
• Separate servers for React and React Native, each with its own dev API

Use Cases

• AI‑driven coding assistants that can suggest component props and code snippets
• Internal design‑system portals that surface live component docs without publishing a website
• IDE extensions that provide instant autocomplete and documentation lookup
• CI pipelines that validate component usage against the latest design tokens

FAQ

Q: Do I need to build the project before running the server? A: No. The npx commands fetch pre‑built binaries and start the server directly.

Q: Which ports are used? A: React MCP runs on http://localhost:8787; Native MCP runs on http://localhost:8788.

Q: How is the data kept up‑to‑date? A: The servers pull the latest component metadata from the HeroUI monorepo during each release; you can also run pnpm extract:react or pnpm extract:native locally to regenerate data.

Q: Can I run both servers simultaneously? A: Yes – they listen on different ports and operate independently.

Q: Is there a way to customize environment variables? A: Only the extraction scripts require Cloudflare R2 and GitHub credentials; the runtime servers do not need additional env vars.

HeroUI MCP Monorepo

Model Context Protocol (MCP) servers for the HeroUI design system. Access HeroUI component documentation directly in your AI assistant.

MCPs

MCP	Description	Docs
@heroui/react-mcp	MCP server for web (@heroui/react) component docs, examples, and theme data	README
@heroui/native-mcp	MCP server for React Native (@heroui/native) component docs, examples, and theme data	README

Quick Start

Installation

Choose your package based on your platform:

For Web (React/Next.js):

# Cursor, Claude Code, Windsurf, etc.
npx -y @heroui/react-mcp@latest

For React Native:

npx -y @heroui/native-mcp@latest

See package-specific READMEs for detailed installation instructions for your IDE.

What's Included

• 🔍 Component Discovery - Search and browse all HeroUI components
• 📚 Complete Documentation - Props, types, and usage examples
• 🎨 Theme Information - Access theme variables and design tokens
• 💻 Source Code - View component implementation and styles
• 🔄 Always Up-to-Date - Latest component data fetched automatically

Local Development

# Clone and install
git clone https://github.com/heroui-inc/heroui-mcp.git
cd heroui-mcp
pnpm install

# Set up environment variables (required for data extraction)
cp .env.example .env
# Edit .env with your Cloudflare R2 and GitHub credentials

Available Scripts

Build Commands:

pnpm build                    # Build all packages
pnpm build:react              # Build React MCP only
pnpm build:native             # Build Native MCP only

Development Servers:

pnpm dev                      # Start all dev servers (excludes mastra)
pnpm dev:react                # React MCP API server (http://localhost:8787)
pnpm dev:native               # Native MCP API server (http://localhost:8788)
pnpm dev:mastra               # Mastra playground server (http://localhost:4111)

Testing & Inspection:

pnpm inspect:react            # Launch MCP Inspector for React
pnpm inspect:native           # Launch MCP Inspector for Native
pnpm lint                     # Run linting
pnpm typecheck                # Run type checking
pnpm test                     # Run tests

Data Extraction:

pnpm extract:react            # Extract React component data
pnpm extract:native           # Extract Native component data

Code Quality:

pnpm format                   # Format code with Prettier
pnpm clean                    # Clean build artifacts
pnpm release:check            # Pre-release validation

See CONTRIBUTING.md for detailed development setup and architecture information.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, architecture details, and contribution guidelines.

Please adhere to our Code of Conduct in all interactions.

Support

• 📖 Documentation
• 💬 Discord Community
• 🐦 X (Twitter)
• 🐛 GitHub Issues
• 📧 Email Support

License

MIT