MCP Server

The HeroUI Pro MCP server gives your AI agent access to both @heroui-pro/react (Pro) and @heroui/react (OSS) — component docs, CSS styles, theme variables, source code, and setup guides — all from a single connection. It can also import generated AI Chat UIs and saved Design Systems into your local project.

Setup

Add the Pro MCP to your editor:

{
  "mcpServers": {
    "heroui-pro": {
      "url": "https://mcp.heroui.pro/mcp",
      "headers": {
        "x-heroui-personal-token": "HEROUI_PERSONAL_TOKEN"
      }
    }
  }
}

claude mcp add --transport http heroui-pro https://mcp.heroui.pro/mcp --header "x-heroui-personal-token: HEROUI_PERSONAL_TOKEN"

{
  "mcpServers": {
    "heroui-pro": {
      "type": "http",
      "url": "https://mcp.heroui.pro/mcp",
      "headers": {
        "x-heroui-personal-token": "HEROUI_PERSONAL_TOKEN"
      }
    }
  }
}

{
  "servers": {
    "heroui-pro": {
      "url": "https://mcp.heroui.pro/mcp",
      "headers": {
        "x-heroui-personal-token": "HEROUI_PERSONAL_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "heroui-pro": {
      "url": "https://mcp.heroui.pro/mcp",
      "headers": {
        "x-heroui-personal-token": "HEROUI_PERSONAL_TOKEN"
      }
    }
  }
}

{
  "context_servers": {
    "heroui-pro": {
      "url": "https://mcp.heroui.pro/mcp",
      "headers": {
        "x-heroui-personal-token": "HEROUI_PERSONAL_TOKEN"
      }
    }
  }
}

[mcp_servers.heroui-pro]
url = "https://mcp.heroui.pro/mcp"
http_headers = { "x-heroui-personal-token" = "HEROUI_PERSONAL_TOKEN" }

Get your HEROUI_PERSONAL_TOKEN from the Pro dashboard.

Available Tools

get_css

• get_css() — list available Pro + OSS component names
• get_css({ components: ["sheet", "sidebar"] }) — Pro BEM CSS
• get_css({ components: ["button", "card"] }) — OSS BEM CSS

get_theme_variables

• get_theme_variables() — list available themes
• get_theme_variables({ theme: "default" }) — Pro base tokens + OSS default tokens
• get_theme_variables({ theme: "brutalism" }) — full Pro theme variant CSS

get_docs

Pro and OSS docs use distinct path prefixes so there's no ambiguity:

• Pro: /pro/docs/react/getting-started/theming
• OSS: /docs/react/getting-started/theming

Import an AI Chat

Use these tools when you want to bring a generated UI from HeroUI AI Chat into a local project.

Workflow:

1. Call get_chat_export_manifest({ chatId }) — returns commitSha, file metadata, recommendedPaths, previewUrl, and agent instructions
2. Inspect the target project and decide which paths to fetch (start with recommendedPaths)
3. Call get_chat_export_files({ chatId, commitSha, paths }) — fetch file contents in chunks of at most 25 paths
4. Adapt the returned files into the project — do not overwrite unrelated local files without asking

get_chat_export_manifest({ chatId: "YOUR_CHAT_ID" })

get_chat_export_files({
  chatId: "YOUR_CHAT_ID",
  commitSha: "abc1234",
  paths: ["package.json", "src/App.tsx", "src/main.tsx"]
})

You can copy a ready-made MCP prompt from the chat export menu in the dashboard.

Import a Design System

Use these tools when you want to apply a saved Design System to a local project.

Workflow:

1. Call get_design_system_manifest({ designSystemId }) — returns name, variables, overrides, brand metadata, asset URLs, custom fonts, available outputs, and recommended outputs
2. Inspect the target project
3. Call get_design_system_export({ designSystemId, outputs }) for the outputs you need
4. Adapt the returned files into the project — do not overwrite unrelated local files without asking

Recommended outputs for most React projects: css, design, and product. Add native-css for HeroUI Native projects.

get_design_system_manifest({ designSystemId: "YOUR_DESIGN_SYSTEM_ID" })

get_design_system_export({
  designSystemId: "YOUR_DESIGN_SYSTEM_ID",
  outputs: ["css", "design", "product"]
})

You can copy a ready-made MCP prompt from the Design System code panel in the dashboard.

Start Prompting

Build a settings page with a Sidebar, CellSwitch toggles, CellSelect dropdowns, and a CellSlider for font size

Create a dashboard with KPI cards, TrendChips, and an AreaChart for weekly revenue

Show me the BEM classes for the Sheet component — I want to customize the overlay and content styles

What props does the Command component accept? Show me an example with keyboard shortcuts

Use the HeroUI Pro MCP to import the generated UI from chat YOUR_CHAT_ID. Start with get_chat_export_manifest, inspect this project, then fetch and adapt the recommended files. Do not overwrite unrelated local files without asking.

Use the HeroUI Pro MCP to import design system YOUR_DESIGN_SYSTEM_ID. Start with get_design_system_manifest, inspect this project, then fetch and adapt the recommended outputs with get_design_system_export. Use its saved tokens, brand guidance, fonts, and assets as the source of truth. Do not overwrite unrelated local files without asking.

Troubleshooting