MCP (Model Context Protocol) integration

Connect Untitled UI to Claude Code or Cursor via MCP server. Access and compose React components directly from your AI assistant with natural language.

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:

Ask Claude to "add a button component to my project"
Request "create a dashboard layout with sidebar navigation"
Get complete page templates: "build a landing page with hero and pricing sections"
Search components: "find components for data visualization"

Prerequisites

Before integrating the MCP server, ensure you have:

Claude Code, Cursor, or Gemini CLI 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 subscription.

How it works

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

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

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

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.

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

When using OAuth:

Add the MCP server without any authentication headers
When you access PRO components, you'll be prompted to log in via browser
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:

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

Get your API key from the Untitled UI dashboard.

Option 3: No authentication (free components only)

For free components only, no authentication is required:

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

Claude Code integration

Set up the MCP server with Anthropic's Claude Code CLI.

Quick start

Add the Untitled UI MCP server:

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:

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 from the Untitled UI dashboard.

Manual configuration

Create or edit ~/.claude.json:

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

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

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

Start using

Launch Claude Code in your project directory:

claude

Now you can interact with Untitled UI components naturally:

📝 "Add a button component to my project"
📝 "I need a contact form with validation"
📝 "Build a pricing page with three tiers"
📝 "Add a data table with sorting and pagination"

Cursor integration

Set up the MCP server with Cursor IDE.

Quick start

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

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

With API key (PRO components)

For PRO access, add your API key:

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

You can also use environment variables:

{
  "mcpServers": {
    "untitledui": {
      "url": "https://www.untitledui.com/react/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNTITLEDUI_API_KEY}"
      }
    }
  }
}

Then set the environment variable:

export UNTITLEDUI_API_KEY="your_api_key_here"

Restart Cursor to load the new MCP configuration.

Gemini CLI integration

Set up the MCP server with Google's Gemini CLI.

Quick start (OAuth)

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

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

When you access PRO components, Gemini CLI will automatically handle OAuth authentication and prompt you to log in via browser.

With API key (alternative)

For API key authentication instead of OAuth:

{
  "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 from the Untitled UI dashboard.

Restart Gemini CLI to load the new MCP configuration.

Available tools

The MCP server provides six tools for component management:

Search and discovery

list_components - Browse components by category

"List all base components"
"Show me marketing components"
"What dashboard components are available?"

search_components - Search by functionality

"Find components for forms"
"Search for data visualization components"
"Show me components with navigation"

Component installation

get_component - Get and install a single component

"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 available page templates

"Show me all landing page templates"
"List dashboard templates with sidebar layout"
"What marketing page templates are available?"

get_page_template_files - Install a complete page template

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

Example workflows

Building a dashboard

User: "I need to build a dashboard with sidebar navigation and a data table"
 
AI Assistant: Let me find the right template for you.
[Searches for dashboard templates]
[Finds dashboards-01 with sidebar layout]
[Runs: npx untitledui@latest example dashboards-01/01 --yes]
[Dashboard installed with all components and dependencies]

Adding components

User: "Add a pricing section to my landing page"
 
AI Assistant: I'll add a pricing component for you.
[Searches for pricing components]
[Finds pricing-section-01]
[Runs: npx untitledui@latest add pricing-section-01 --yes]
[Component installed with proper imports]

Component discovery

User: "What components do you have for handling user input?"
 
AI Assistant: Let me search the Untitled UI library.
[Searches with query "input"]
[Lists: input, form, checkbox, radio, select, textarea, etc.]
[Shows descriptions and access levels for each]

Free vs PRO

Free components (no API key required)

Base UI components (buttons, inputs, forms)
Core application components
Basic page templates

PRO components (API key required)

Advanced marketing components
Complex dashboard templates
PRO page layouts
All component variants

The MCP server automatically filters components based on your access level. Without an API key, you'll only see free components.

Resources

The MCP server also provides browseable resources:

untitledui://components - Browse all components
untitledui://components/base - Core UI components
untitledui://components/application - Complex app components
untitledui://components/marketing - Marketing sections
untitledui://templates - Complete page templates
untitledui://examples - Usage examples and patterns

Troubleshooting

MCP server not connecting

Verify your configuration syntax
Check that the URL is correct: https://www.untitledui.com/react/api/mcp

Try removing and re-adding the MCP:

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:

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

PRO access denied

{
  "error": "PRO access required for this component"
}

Add your API key to the MCP configuration or use OAuth
Verify your API key is valid
Ensure your subscription 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

Need help? Check our GitHub repository for examples, or open an issue if you run into any problems. Our community is here to help!

Monorepo components.json