export const title = "MCP (Model Context Protocol) integration"
export const description = "Connect Untitled UI to Claude Code or Cursor via MCP server. Access and compose React components directly from your AI assistant with natural language."

<Divider />

## Overview

The Untitled UI MCP server enables AI assistants like Claude Code and Cursor to directly access our component library. Instead of copying and pasting components manually, your AI assistant can browse, search, and install components for you using natural language.

### What you can do
- Search with natural language: "find a login page with customer testimonials and star ratings"
- Get the best-matching template: "I need a dark SaaS landing page with pricing comparison"
- Install components: "add a modal dialog for profile settings with avatar upload"
- Browse by category: "show me all dashboard templates with sidebar navigation"

For PRO users, our MCP server uses **semantic search powered by multimodal AI embeddings** — it understands both the text description and visual appearance of every component to find the best match for your query. Without a PRO license, searches use keyword matching against component names and descriptions.

<Divider />

## Prerequisites

Before integrating the MCP server, ensure you have:

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup), [Cursor](https://cursor.com), [Codex](https://developers.openai.com/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [OpenCode](https://opencode.ai) installed
- A project initialized with the Untitled UI CLI (`npx untitledui init`)
- Node.js 18+ installed

**Note:** Free components work without a need for authentication. For PRO components, you'll need an [Untitled UI PRO license](https://www.untitledui.com/buy/react) (a one-time purchase with free updates for life).

<Divider />

## How it works

The MCP server helps your AI assistant discover and install components:

1. **You ask** for a component or page template in natural language
2. **AI searches** the Untitled UI library using MCP tools
3. **AI receives** a CLI command to install the component
4. **AI runs** the command in your terminal
5. **Component is installed** with all dependencies automatically

This approach saves tokens and ensures components are installed correctly with proper dependencies and file structure.

<Divider />

## Authentication options

The Untitled UI MCP server supports three authentication methods:

### Option 1: OAuth (recommended)

Our MCP server supports OAuth 2.1 with PKCE for secure authentication. MCP clients that support OAuth (like Claude Code) will automatically handle the login flow.

```bash
claude mcp add untitledui --transport http https://www.untitledui.com/react/api/mcp
```

When using OAuth:
1. Add the MCP server without any authentication headers
2. When you access PRO components, you'll be prompted to log in via browser
3. After authentication, your session persists automatically

This is the recommended approach as it:
- Doesn't require managing API keys
- Automatically refreshes your session
- Works seamlessly with Claude Code's OAuth support

### Option 2: API key header

For clients that don't support OAuth, you can use your API key directly:

```bash
claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your actual API key:

<div className="not-typography mt-5">
    <FileCard
        type="token"
        access="react"
        title="Untitled UI React – API key"
        subtitle="Configure your MCP server with your API key:"
        noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
    />
</div>

### Option 3: No authentication (free components only)

For free components only, no authentication is required:

```bash
claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp
```

<Divider />

## Integration setup

Choose your AI assistant below and follow the steps to connect the Untitled UI MCP server.

<Tabs className="w-full mt-8">
    <TabList type="underline" items={[{ id: 'claude', label: 'Claude Code' }, { id: 'cursor', label: 'Cursor' }, { id: 'codex', label: 'Codex' }, { id: 'gemini', label: 'Gemini CLI' }, { id: 'opencode', label: 'OpenCode' }]} />

    <TabPanel id="claude">
        ### Quick start

        Add the Untitled UI MCP server:

        ```bash
        claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp
        ```

        Claude Code will automatically use OAuth for PRO component access. When you first request a PRO component, you'll be prompted to authenticate via your browser.

        ### With API key (alternative)

        If you prefer using an API key instead of OAuth:

        ```bash
        claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Manual configuration

        Create or edit `~/.claude.json`:

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "type": "http",
              "url": "https://www.untitledui.com/react/api/mcp"
            }
          }
        }
        ```

        With API key for PRO access (alternative to OAuth):

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "type": "http",
              "url": "https://www.untitledui.com/react/api/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Verify connection

        Check that the MCP server is connected:

        ```bash
        claude mcp list
        ```

        You can also verify inside a Claude Code session by typing `/mcp` to see the connection status of all configured servers.

        ### Start using

        Now you can interact with Untitled UI components naturally:

        ```
        "I need a login page with customer reviews and social proof"
        "Build a fintech dashboard with charts and credit card visuals"
        "Add a modal for profile settings with avatar upload"
        "Find a dark landing page with pricing comparison table"
        ```
    </TabPanel>

    <TabPanel id="cursor">
        ### Quick start

        Create a `.cursor/mcp.json` file in your project root:

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "url": "https://www.untitledui.com/react/api/mcp"
            }
          }
        }
        ```

        ### With API key (PRO components)

        For PRO access, add your API key:

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "url": "https://www.untitledui.com/react/api/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Verify connection

        Restart Cursor to load the new MCP configuration. Then verify the server is connected by opening the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and running **"Cursor settings: Tools & MCP"**. The Untitled UI server should show a green connected status.

        ### Start using

        Open Cursor's AI chat and start asking for components:

        ```
        "I need a login page with customer reviews and social proof"
        "Build a fintech dashboard with charts and credit card visuals"
        "Add a modal for profile settings with avatar upload"
        "Find a dark landing page with pricing comparison table"
        ```
    </TabPanel>

    <TabPanel id="codex">
        ### Quick start

        Add the Untitled UI MCP server using the Codex CLI:

        ```bash
        codex mcp add untitledui --url https://www.untitledui.com/react/api/mcp
        ```

        Codex will automatically detect OAuth support and prompt you to log in via your browser when you access PRO components. You can also trigger the login manually:

        ```bash
        codex mcp login untitledui
        ```

        ### With API key (alternative)

        If you prefer using an API key instead of OAuth:

        ```bash
        codex mcp add untitledui --url https://www.untitledui.com/react/api/mcp --bearer-token-env-var UNTITLEDUI_API_KEY
        ```

        Then set the environment variable (add to your `~/.zshrc` or `~/.bashrc` to persist):

        ```bash
        export UNTITLEDUI_API_KEY="YOUR_API_KEY"
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Manual configuration

        Create or edit `~/.codex/config.toml` (global) or `.codex/config.toml` (project-specific):

        ```json
        [mcp_servers.untitledui]
        url = "https://www.untitledui.com/react/api/mcp"
        ```

        With API key for PRO access (alternative to OAuth):

        ```json
        [mcp_servers.untitledui]
        url = "https://www.untitledui.com/react/api/mcp"
        bearer_token_env_var = "UNTITLEDUI_API_KEY"
        ```

        Set the environment variable with your API key:

        ```bash
        export UNTITLEDUI_API_KEY="YOUR_API_KEY"
        ```

        Alternatively, you can pass the header directly (not recommended for shared configs):

        ```json
        [mcp_servers.untitledui]
        url = "https://www.untitledui.com/react/api/mcp"
        http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
        ```

        ### Verify connection

        Restart Codex to load the new MCP configuration. Then verify inside a Codex session by typing `/mcp` to see your active MCP servers and their connection status.

        ### Start using

        Start a Codex session and ask for components:

        ```
        "I need a login page with customer reviews and social proof"
        "Build a fintech dashboard with charts and credit card visuals"
        "Add a modal for profile settings with avatar upload"
        "Find a dark landing page with pricing comparison table"
        ```
    </TabPanel>

    <TabPanel id="gemini">
        ### Quick start

        Add the Untitled UI MCP server using the Gemini CLI:

        ```bash
        gemini mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp
        ```

        Gemini CLI will automatically handle OAuth authentication when you access PRO components.

        ### With API key (alternative)

        ```bash
        gemini mcp add --transport http --header "Authorization: Bearer YOUR_API_KEY" untitledui https://www.untitledui.com/react/api/mcp
        ```

        ### Manual configuration

        Create or edit `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project-specific):

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "httpUrl": "https://www.untitledui.com/react/api/mcp"
            }
          }
        }
        ```

        With API key for PRO access (alternative to OAuth):

        ```json
        {
          "mcpServers": {
            "untitledui": {
              "httpUrl": "https://www.untitledui.com/react/api/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Verify connection

        Check that the MCP server is connected:

        ```bash
        gemini mcp list
        ```

        You can also verify inside a Gemini CLI session by typing `/mcp` to see connection status.

        ### Start using

        Start a Gemini CLI session and ask for components:

        ```
        "I need a login page with customer reviews and social proof"
        "Build a fintech dashboard with charts and credit card visuals"
        "Add a modal for profile settings with avatar upload"
        "Find a dark landing page with pricing comparison table"
        ```
    </TabPanel>

    <TabPanel id="opencode">
        ### Quick start

        Add the Untitled UI MCP server using the OpenCode CLI:

        ```bash
        opencode mcp add
        ```

        When prompted, select **remote** as the server type and enter the URL:

        ```
        https://www.untitledui.com/react/api/mcp
        ```

        OpenCode will automatically handle OAuth for PRO component access. When you first request a PRO component, you'll be prompted to authenticate via your browser.

        ### Manual configuration

        Create or edit `opencode.json` in your project root (or `~/.config/opencode/opencode.json` for global config):

        ```json
        {
          "$schema": "https://opencode.ai/config.json",
          "mcp": {
            "untitledui": {
              "type": "remote",
              "url": "https://www.untitledui.com/react/api/mcp"
            }
          }
        }
        ```

        ### With API key (alternative)

        If you prefer using an API key instead of OAuth:

        ```json
        {
          "$schema": "https://opencode.ai/config.json",
          "mcp": {
            "untitledui": {
              "type": "remote",
              "url": "https://www.untitledui.com/react/api/mcp",
              "oauth": false,
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_API_KEY` with your actual API key:

        <div className="not-typography mt-5">
            <FileCard
                type="token"
                access="react"
                title="Untitled UI React – API key"
                subtitle="Configure your MCP server with your API key:"
                noAccessSubtitle="Upgrade to Untitled UI React PRO to access PRO components."
            />
        </div>

        ### Verify connection

        Check that the MCP server is connected:

        ```bash
        opencode mcp list
        ```

        If you run into issues, use the debug command:

        ```bash
        opencode mcp debug untitledui
        ```

        Restart OpenCode to load the new MCP configuration.

        ### Start using

        Start an OpenCode session and ask for components:

        ```
        "I need a login page with customer reviews and social proof"
        "Build a fintech dashboard with charts and credit card visuals"
        "Add a modal for profile settings with avatar upload"
        "Find a dark landing page with pricing comparison table"
        ```
    </TabPanel>
</Tabs>

<Divider />

## Available tools

The MCP server provides seven tools. The two most important ones — `search_components` and `get_page_templates` — use semantic search to understand what you're looking for, even when your description doesn't match exact component names. Semantic ranking requires PRO authentication; unauthenticated requests fall back to keyword matching.

### Search and discovery

**`search_components`** — find any component using natural language

This is the primary search tool. Describe what you need in plain language. With PRO authentication it uses multimodal AI embeddings trained on both the text description and screenshot of every component, so the search understands visual concepts like "split layout", "testimonial quote", or "dark background" and matches them to the right components. Without authentication it scores results by keyword matches on names and descriptions, and PRO components are hidden.

```
"Find a login page with customer reviews and star ratings"
"Modal dialog for profile settings with avatar upload"
"Dark pricing section with feature comparison table"
"Split-layout signup page with app mockup"
```

Parameters:
- `query` — describe what you need in natural language (required)
- `category_filter` — narrow results to a category: `base`, `application`, `marketing`, `foundations`, `shared-assets`
- `limit` — maximum number of results (default: 20)
- `key` — API key for PRO component access

Each result includes an AI-generated description, a screenshot URL, key features (e.g., `avatar-upload`, `carousel-navigation`), and a match reason explaining why it ranked.

**`list_components`** — browse all components by category

Use this when you want to explore what's available rather than search for something specific.

```
"List all base components"
"Show me marketing components"
```

Parameters:
- `category` — filter by: `base`, `application`, `marketing`, `foundations`, `shared-assets`
- `skip` / `limit` — for pagination (default: 0 / 100)
- `key` — API key for PRO component access

### Component installation

**`get_component`** — get a single component and its CLI install command

```
"Add the Button component to my project"
"Install the Modal component"
```

**`get_component_bundle`** — install multiple components at once

```
"Add Button, Modal, and Form components"
"Install all components I need for a contact form"
```

### Page templates

**`get_page_templates`** — browse and search complete page templates

Use this to find full page layouts. Pass a `query` parameter to search by description, or use `category` and `page_type` filters to browse. Includes landing pages, dashboards, settings pages, and auth pages (login, signup, forgot password, email verification).

```
"SaaS landing page with pricing and testimonials"
"Dark themed dashboard with charts and analytics"
"Clean signup page with social login options"
"Show me all contact page templates"
```

Parameters:
- `query` — natural language search. When provided, results are ranked by semantic relevance (PRO authentication required; page templates are PRO-only)
- `page_type` — filter by: `dashboard`, `marketing`, `application`, `all` (default: `all`)
- `category` — specific category: `landing-pages`, `pricing-pages`, `dashboards`, `settings`, `login`, `signup`, `forgot-password`, `email-verification`, and more
- `layout` — layout preference: `sidebar`, `header`, `full-width`
- `limit` — maximum number of templates (default: 10)
- `key` — API key for PRO access

Each template includes an AI-generated description, a section breakdown (hero, features, pricing, testimonials, CTA, etc.), the hero style, a list of UI elements, and a screenshot URL.

**`get_page_template_files`** — install a complete page template (PRO only)

After finding a template with `get_page_templates`, use this tool with the template name to get the CLI install command.

```
"Install the landing page template 01"
"Add the dashboard template to my project"
```

### Icons

**`search_icons`** — search for icons by name or keyword

Use this before importing any icon to verify it exists and get the correct import name.

```
"Find a home icon"
"Search for arrow icons"
```

<Divider />

## Example workflows

Here are a few examples of how AI assistants use the MCP tools to find and install the right components.

### Finding the right login page

```
You: "I need a login page with customer testimonials"

AI searches for "login page with customer reviews and testimonial quote"
→ Finds login-split-quote-image-01 (split layout with testimonial
  quote, portrait photo, and carousel navigation)
→ Runs: npx untitledui@latest add login-split-quote-image-01 --yes
```

With PRO authentication, the semantic search matches "customer testimonials" to a component whose screenshot shows a quote and customer photo — even though the component name doesn't mention "testimonial".

### Building a fintech dashboard

```
You: "I need a fintech dashboard with charts and analytics"

AI searches templates for "fintech dashboard with charts and analytics"
→ Finds dashboards-01/12 (dashboard with charts, credit card visual,
  carousel, date picker, and sidebar navigation)
→ Runs: npx untitledui@latest example dashboards-01/12 --yes
```

### Adding a specific section

```
You: "Add a pricing section with a comparison table"

AI searches for "pricing section with comparison table"
→ Finds pricing-large-table-01 (full-width pricing with three-tier
  comparison table, billing toggle, and feature checkmarks)
→ Runs: npx untitledui@latest add pricing-large-table-01 --yes
```

<Divider />

## Troubleshooting

### MCP server not connecting

1. Verify your configuration syntax
2. Check that the URL is correct: `https://www.untitledui.com/react/api/mcp`
3. Try removing and re-adding the MCP:
   ```bash
   claude mcp remove untitledui
   claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp
   ```

### CLI command fails

If the AI runs a CLI command that fails:

1. Ensure you've initialized Untitled UI: `npx untitledui init`
2. Check that you're in the correct project directory
3. Verify Node.js 18+ is installed

### PRO access denied

```json
{
  "error": "pro_access_required",
  "agent_instructions": "DO NOT attempt to build this from scratch. Instead, ask the user: …",
  "component": "…",
  "auth_methods": {
    "mcp_oauth": "Trigger MCP OAuth authentication flow if available",
    "cli": "npx untitledui@latest login"
  },
  "upgrade_url": "https://buy.polar.sh/…"
}
```

- Add your API key to the MCP configuration or use OAuth
- Verify your API key is valid
- Ensure your license includes access to React PRO components

### Component not found

- Check the component name is correct (use `search_components` to find it)
- Some components may have specific names like `hero-simple-text-01`

<Divider />

**Need help?** Check our [GitHub repository](https://github.com/untitleduico/react/) for examples, or [open an issue](https://github.com/untitleduico/react/issues/) if you run into any problems. Our community is here to help!