---
title: MCP Server
description: Access HeroUI Native documentation directly in your AI assistant
---

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

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-light-new.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-dark-new.jpg"
  alt="HeroUI v3 MCP Server"
/>


The MCP server currently supports **heroui-native** and [stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). Published at `@heroui/native-mcp` on npm. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp).

<Callout>
  As we add more components to HeroUI Native, they'll be available in the MCP server too.
</Callout>

## Quick Setup

**Cursor:**

<div className="flex items-center gap-3 mb-4">
  <a
    href="https://link.heroui.com/native-mcp-cursor-install"
    className="button button--tertiary button--sm no-underline"
  >
    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
    </svg>
    <span  >Install in Cursor</span>
  </a>
</div>

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

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "heroui-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native -- npx -y @heroui/native-mcp@latest
```

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

```json title=".mcp.json"
{
  "mcpServers": {
    "heroui-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native 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-native": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@heroui/native-mcp@latest"]
    }
  }
}
```

After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-native 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-native]
command = "npx"
args = ["-y", "@heroui/native-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-native": {
      "type": "local",
      "command": ["npx", "-y", "@heroui/native-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 Native in my Expo app"
- "Show me all HeroUI Native components"
- "What props does the Button component have?"
- "Give me an example of using the Card component"
- "What are the theme variables for dark mode?"

### Automatic Updates

The MCP server can help you upgrade to the latest HeroUI Native version:

```bash
"Hey Cursor, update HeroUI Native 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 Native components |
| `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns for one or more components |
| `get_theme_variables` | Access theme variables for colors, typography, spacing with light/dark mode support |
| `get_docs` | Browse the full HeroUI Native documentation including guides and principles (use path `/docs/native/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/native-mcp)
- [GitHub Repository](https://github.com/heroui-inc/heroui-mcp)
- [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)