# MCP Server
**Category**: react
**URL**: https://www.heroui.com/docs/react/getting-started/mcp-server
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/getting-started/(ui-for-agents)/mcp-server.mdx
> Access HeroUI v3 documentation directly in your AI assistant
***
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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). Published at `@heroui/react-mcp` on npm. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp).
As we add more components to HeroUI v3, they'll be available in the MCP server too.
## Quick Setup
### Cursor
Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:
```json title=".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](https://cursor.com/docs/context/mcp).
### Claude Code
Run this command in your terminal:
```bash
claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
```
Or manually add to your project's `.mcp.json` file:
```json title=".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](https://docs.claude.com/en/docs/claude-code/mcp) for more details.
### Windsurf
Add the HeroUI server to your project's `.windsurf/mcp.json` configuration file:
```json title=".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](https://docs.windsurf.com/windsurf/cascade/mcp) for more details.
### Zed
Add the HeroUI server to your `settings.json` configuration file. Open settings via Command Palette (`zed: open settings`) or use `Cmd-,` (Mac) / `Ctrl-,` (Linux):
```json title="settings.json"
{
"context_servers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"],
"env": {}
}
}
}
```
After adding the configuration, restart Zed and open the Agent Panel settings view. Check that the indicator dot next to the heroui server is green with "Server is active" tooltip.
See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp) 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:
```json title=".vscode/mcp.json"
{
"servers": {
"heroui-react": {
"type": "stdio",
"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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
### Codex
Add the HeroUI server to your `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):
```toml title="config.toml"
[mcp_servers.heroui-react]
command = "npx"
args = ["-y", "@heroui/react-mcp@latest"]
```
After adding the configuration, restart Codex and run `/mcp` in the TUI to verify the server is active.
See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
### OpenCode
Add the HeroUI server to your project's `opencode.json` configuration file:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"heroui-react": {
"type": "local",
"command": ["npx", "-y", "@heroui/react-mcp@latest"]
}
}
}
```
After adding the configuration, restart OpenCode to activate the MCP server.
See the [OpenCode MCP documentation](https://open-code.ai/docs/en/mcp-servers) 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?"
### Automatic Updates
The MCP server can help you upgrade to the latest HeroUI version:
```bash
"Hey Cursor, update HeroUI to the latest version"
```
Your AI assistant will automatically:
- Compare your current version with the latest release
- Review the changelog for breaking changes
- Apply the necessary code updates to your project
This works for any version upgrade, whether you're updating to the latest stable or pre-release version.
## Available Tools
The MCP server provides these tools to AI assistants:
| Tool | Description |
|------|-------------|
| `list_components` | List all available HeroUI v3 components |
| `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns for one or more 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_variables` | Access theme variables for colors, typography, spacing with light/dark mode support |
| `get_docs` | Browse the full HeroUI v3 documentation including guides and principles (use path `/docs/react/getting-started/quick-start` for installation instructions) |
## Troubleshooting
**Requirements:** Node.js 22 or higher. The package will be automatically downloaded when using `npx`.
**Need help?** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord Community](https://discord.gg/heroui)
## Links
- [npm Package](https://www.npmjs.com/package/@heroui/react-mcp)
- [GitHub Repository](https://github.com/heroui-inc/heroui-mcp)
- [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)