HeroUI React MCP Server

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

> Note: Currently supports @heroui/react v3 only. For @heroui/native (React Native components), use @heroui/native-mcp.

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

$3


Or add manually to Cursor Settings → Features → MCP Servers:

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

$3

Quick Install (CLI):
`bash
claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
`

Or manually add to your Claude Code configuration:

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

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

$3

Quick Install (CLI):
`bash
codex mcp add heroui-react -- npx -y @heroui/react-mcp@latest
`

Or manually add to your Codex configuration file:

macOS/Linux: ~/.codex/config.toml
Windows: %USERPROFILE%\.codex\config.toml

`toml
[mcp_servers.heroui-react]
command = "npx"
args = ["-y", "@heroui/react-mcp@latest"]
`

For more configuration options, see the Codex MCP documentation.

$3

Add to Windsurf configuration → MCP Servers:

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

$3

Add to your VS Code settings:

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

$3

Add to your Claude Desktop configuration:

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

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

Usage

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

- "Show me the HeroUI v3 installation guide"
- "Show me all HeroUI v3 components"
- "Get the complete documentation for the Button component"
- "Show me examples of using the Card component"
- "Get the source code for the Button component"
- "Show me the CSS styles for Card"
- "What are the theme variables?"
- "Explain HeroUI's theming guide"

Available Tools

The MCP server provides these tools to AI assistants:

$3

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

`javascript
// No parameters required
`

$3

Get complete component documentation (including examples, props, usage) directly from v3.heroui.com. This tool consolidates component information, props, and examples into a single call.

`javascript
// Parameters
{
components: ["Button"] // Required - array of component names (case-sensitive)
}

// Examples
{
components: ["Button"] // Single component
}
{
components: ["Button", "Card", "TextField"] // Multiple components
}
`

Note: Always use list_components first to verify component names before calling this tool.

$3

Get the React/TypeScript source code (.tsx) for HeroUI components. Returns the internal implementation for learning purposes or debugging.

`javascript
// Parameters
{
components: ["Button"] // Required - array of component names
}

// Examples
{
components: ["Button", "TextField"] // Get source for multiple components
}
`

Note: This shows internal implementation - use get_component_docs for usage examples.

$3

Get the CSS styles (.css) for HeroUI components. Returns the complete CSS implementation including all variants and states.

`javascript
// Parameters
{
components: ["Button"] // Required - array of component names
}

// Examples
{
components: ["Button", "Card"] // Get styles for multiple components
}
`

Note: These are framework-agnostic styles from @heroui/styles package. For React components, prefer using @heroui/react.

$3

Get HeroUI v3 React documentation content for guides, principles, and release notes (NOT component docs). Fetches official documentation from v3.heroui.com.

`javascript
// Parameters
{
path: string // Required - exact documentation path
}

// Examples
{
path: "/docs/react/getting-started/theming" // Get theming guide
}
{
path: "/docs/react/releases/v3-0-0-beta-3" // Release notes
}
`

Note: For component documentation, use get_component_docs instead. All React documentation paths start with /docs/react/ prefix.

$3

Get HeroUI v3 default theme variables and design tokens (actual variable values). Includes both light and dark mode variables for all categories.

Note: For theme documentation and guides, use get_docs({ path: "/docs/react/getting-started/theming" }) instead.

Troubleshooting

$3

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

$3

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

$3

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 our Code of Conduct.

Support

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

License

MIT