HeroUI MCP Server

Access HeroUI component documentation directly in your AI assistant via Model Context Protocol (MCP).

Note: Currently supports @heroui/react v3 only. Support for heroui-native coming soon.

Features

• Complete component documentation for HeroUI React v3
• Search and browse components
• Get props, types, and usage examples
• Always up-to-date with latest versions

Configuration

Cursor

Add to Cursor Settings → Features → MCP Servers:

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

Claude Code

Add to your Claude Code configuration:

macOS: ~/Library/Application Support/Claude/claude_mcp_settings.json Windows: %APPDATA%\Claude\claude_mcp_settings.json

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

Windsurf

Add to Windsurf configuration → MCP Servers:

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

VS Code (with MCP extension)

Add to your VS Code settings:

{
  "mcp.servers": {
    "heroui": {
      "command": "npx",
      "args": ["-y", "@heroui/mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

IDE Rules Setup (Optional)

For better accuracy when working with HeroUI components, add the HeroUI rules file to your IDE:

Cursor / Windsurf / Claude Code

Copy heroui-web-rules.mdc to your project's .cursor/rules/ directory:

# Create rules directory if it doesn't exist
mkdir -p .cursor/rules

# Copy the HeroUI rules file
curl -o .cursor/rules/heroui-web-rules.mdc https://raw.githubusercontent.com/heroui-inc/heroui-mcp/main/heroui-web-rules.mdc

This provides your AI assistant with:

• Correct HeroUI v3 component patterns
• MCP tool usage guidance
• Theme customization rules
• Best practices for implementation

Usage

Once configured, you can ask your AI assistant questions like:

• "Help me install HeroUI v3 in my Next.js app"
• "Show me all HeroUI components"
• "What props does the Button component have?"
• "Give me an example of using the Card component"
• "Check if I'm using the latest version of HeroUI"
• "Get the source code for the Button component"
• "Show me the CSS styles for Card"
• "What are the theme variables for dark mode?"
• "Explain HeroUI's color customization guide"

Available Tools

The MCP server provides these tools to AI assistants:

installation

Get complete installation guide for @heroui/react v3 in your React/Next.js project.

// Parameters
{
  framework: "next-app" | "next-pages" | "vite" | "general",  // Required
  packageManager?: "npm" | "pnpm" | "yarn" | "bun"            // Optional, defaults to npm
}

list_components

List all available HeroUI components (always returns latest version).

// No parameters required

get_component_info

Get complete information about a specific HeroUI component including description, anatomy, props, and examples.

// Parameters
{
  component: "Button"  // Required - must be one of the available components
}

get_component_props

Get detailed props information for a specific HeroUI component.

// Parameters
{
  component: "Button"  // Required - must be one of the available components
}

get_component_examples

Get usage examples for a specific HeroUI component.

// Parameters
{
  component: "Button"  // Required - must be one of the available components
}

get_component_source_code

Get the React/TypeScript source code (.tsx) for a HeroUI component.

// Parameters
{
  component: "Button"  // Required - must be one of the available components
}

get_component_source_styles

Get the CSS styles (.css) for a HeroUI component.

// Parameters
{
  component: "Button"  // Required - must be one of the available components
}

get_theme_info

Get HeroUI theme variables with an optimized structure that extracts common variables (base and calculated) shared between light and dark modes.

// Parameters
{
  theme?: "default",   // Optional, defaults to "default"
  mode?: "light" | "dark" | "both", // Optional, defaults to "both"
  category?: "colors" | "typography" | "spacing" | "borders" | "shadows" | "animations" | "all" // Optional
}

get_docs

Get HeroUI v3 documentation content for guides, principles, and component docs.

// Parameters
{
  path: string  // Required - documentation path (e.g., "/docs/introduction", "/docs/components/button")
}

Development

Local Testing with Mastra Playground

For local development and testing of MCP tools, you can use the built-in Mastra playground:

# Install dependencies
pnpm install

# Configure environment (one-time setup)
cd mastra
cp .env.example .env
# Edit .env and add your AI model API key

# Start the playground
cd ..
pnpm dev:mastra

Then open http://localhost:4111 in your browser to test MCP tools interactively with an AI agent.

See mastra/README.md for detailed setup instructions.

Troubleshooting

MCP server not found

Ensure you have Node.js 18+ installed. The package will be automatically downloaded when using npx.

Connection issues

If you're behind a corporate firewall, you may need to configure proxy settings or use a custom API URL.

Need help?

Check our troubleshooting guide or ask in our Discord community.

Contributing

Contributions are always welcome!

See CONTRIBUTING.md for ways to get started.

Please adhere to this project's CODE_OF_CONDUCT.

Support

• X
• GitHub Issues
• Discord Community
• Email Us

License

MIT