MCP Server | HeroUI v3 (Previously NextUI) - The design system you don't have to build

The HeroUI MCP Server gives AI assistants direct access to HeroUI v3 component documentation, making it easier to build with HeroUI in AI-powered development environments.

The MCP server currently supports @heroui/react v3 only and stdio transport and is published at @heroui/react-mcp on npm. View the source code on GitHub.

As we add more components to HeroUI v3, they'll be available in the MCP server too.

Quick Setup

Cursor

Install in Cursor

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

.cursor/mcp.json

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

Alternatively, add the following to your ~/.cursor/mcp.json file. To learn more, see the Cursor documentation.

Claude Code

Run this command in your terminal:

claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest

Or manually add to your project's .mcp.json file:

.mcp.json

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

After adding the configuration, restart Claude Code and run /mcp to see the HeroUI MCP server in the list. If you see Connected, you're ready to use it.

See the Claude Code MCP documentation for more details.

Windsurf

Add the HeroUI server to your project's .windsurf/mcp.json configuration file:

.windsurf/mcp.json

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

After adding the configuration, restart Windsurf to activate the MCP server.

See the Windsurf MCP documentation for more details.

VS Code

To configure MCP in VS Code with GitHub Copilot, add the HeroUI server to your project's .vscode/mcp.json configuration file:

.vscode/mcp.json

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

After adding the configuration, open .vscode/mcp.json and click Start next to the heroui-react server.

See the VS Code MCP documentation for more details.

Usage

Once configured, ask your AI assistant questions like:

"Help me install HeroUI v3 in my Next.js/Vite/Astro app"
"Show me all HeroUI components"
"What props does the Button component have?"
"Give me an example 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 for dark mode?"

Available Tools

The MCP server provides these tools to AI assistants:

Tool	Description
`installation`	Get complete installation instructions for your specific framework (Next.js, Vite, etc.) and package manager
`list_components`	List all available HeroUI v3 components
`get_component_info`	Get detailed documentation, anatomy, props, and examples for specific components
`get_component_props`	Get detailed props information for HeroUI components
`get_component_examples`	Get usage examples for HeroUI components
`get_component_source_code`	Access the React/TypeScript source code (.tsx files) for components
`get_component_source_styles`	View the CSS styles (.css files) for components
`get_theme_info`	Access theme variables for colors, typography, spacing with light/dark mode support
`get_docs`	Browse the full HeroUI v3 documentation including guides and principles

Troubleshooting

Requirements

Node.js 18 or higher
The package will be automatically downloaded when using npx

MCP ServerPreview