HeroUI MCP Server

A Model Context Protocol (MCP) server providing comprehensive access to the HeroUI component library documentation. Deploy this MCP to help AI assistants like Claude Code build consistent, well-designed React applications using HeroUI components.

🚀 Quick Deploy

This will deploy your HeroUI MCP server to a URL like: heroui-mcp.<your-account>.workers.dev/sse

📋 What This MCP Provides

This MCP server gives AI assistants instant access to HeroUI's 50+ React components with 7 specialized tools:

Available Tools

1. list_components - Browse all 50 available HeroUI components
2. get_component_info - Get component details, imports, and basic usage
3. get_component_api - View complete API reference with props and types
4. get_component_slots - Explore slot-based customization options
5. get_variants_guide - Learn the extendVariants customization system
6. search_components - Find components by use case (forms, navigation, overlays, etc.)
7. get_theme_info - HeroUI theme system and configuration guide

Component Categories

• Forms: Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Date Pickers
• Navigation: Navbar, Breadcrumbs, Tabs, Links
• Layout: Card, Divider, Spacer, Accordion
• Data Display: Table, Listbox, Pagination, Avatar, User, Badge
• Feedback: Alert, Toast, Progress, Spinner, Skeleton
• Overlays: Modal, Drawer, Popover, Tooltip, Dropdown
• Media: Image, Avatar
• And more: 50+ components total

🔌 Installation

Option 1: Quick Start (if you don't want to deploy to Cloudflare or run your own locally)

Use the public HeroUI MCP server to get started immediately:

Claude Code:

claude mcp add heroui npx mcp-remote https://heroui-mcp-cloudflare.jgentes.workers.dev/sse

Cursor:

Install in Cursor:

To install the HeroUI MCP Server in Cursor, copy and paste the following link into your browser's address bar:

cursor://anysphere.cursor-deeplink/mcp/install?name=heroui&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJtY3AtcmVtb3RlIiwiaHR0cHM6Ly9oZXJvdWktbWNwLWNsb3VkZmxhcmUuamdlbnRlcy53b3JrZXJzLmRldi9zc2UiXX0=

Or manually add to your Cursor settings:

{
  "mcpServers": {
    "heroui": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://heroui-mcp-cloudflare.jgentes.workers.dev/sse"
      ]
    }
  }
}

Option 2: Deploy Your Own

Deploy your own instance to Cloudflare Workers:

1. Click the "Deploy to Cloudflare Workers" button at the top
2. After deployment, your MCP will be available at: https://heroui-mcp-cloudflare.<your-account>.workers.dev/sse
3. Connect to Claude Code:

claude mcp add heroui npx mcp-remote https://heroui-mcp-cloudflare.<your-account>.workers.dev/sse

Or manually edit your config:

{
  "mcpServers": {
    "heroui": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://heroui-mcp-cloudflare.<your-account>.workers.dev/sse"
      ]
    }
  }
}

Option 3: Local Server

For running using the Wrangler CLI:

# Install dependencies
npm install

# Run locally (starts on http://localhost:8787)
npm run dev

Connect to your local instance:

Claude Code:

claude mcp add heroui npx mcp-remote http://localhost:8787/sse

Manual config:

{
  "mcpServers": {
    "heroui": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

🛠️ How It Works

This MCP server fetches documentation directly from heroui.com and provides structured information to AI assistants. It helps ensure:

• ✅ Consistency - Correct HeroUI component usage across projects
• ✅ Efficiency - Quick component discovery prevents unnecessary custom development
• ✅ Accuracy - Direct access to official documentation ensures proper implementation
• ✅ Customization - Full support for HeroUI's slots and variants system
• ✅ Best Practices - Includes accessibility guidelines and proper usage patterns

📚 Example Usage

When connected to Claude Code, you can ask questions like:

• "List all available HeroUI components"
• "Show me how to use the Button component"
• "What slots does the Card component have?"
• "Find components for building forms"
• "How do I customize variants in HeroUI?"

The MCP will provide accurate, up-to-date information from the official HeroUI documentation.

🔧 Customization

To modify the MCP server, edit src/index.ts:

• Update component lists in the COMPONENTS constant
• Add new tools using this.server.tool(...)
• Modify search categories in COMPONENT_MAP
• Add more slot definitions in SLOTS_INFO

📦 Versioning & Releases

This project uses release-it with conventional changelog for versioning.

For Maintainers

To create a new release:

npm run release

This will:

1. Prompt you to select version bump (patch/minor/major)
2. Update package.json version
3. Generate/update CHANGELOG.md from commit messages
4. Create a git tag
5. Push changes to GitHub
6. Create a GitHub release

Commit Message Format

Use Conventional Commits format for automatic changelog generation:

• feat: add new component tool - New features (minor version bump)
• fix: correct slot parsing - Bug fixes (patch version bump)
• docs: update installation guide - Documentation changes
• chore: update dependencies - Maintenance tasks
• BREAKING CHANGE: in commit body - Breaking changes (major version bump)

See CHANGELOG.md for release history.

📄 License

MIT

🙏 Credits

• Built with Cloudflare Workers
• Documentation from HeroUI
• Implements the Model Context Protocol