MCP (Model Context Protocol) integration

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, Codex, 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:

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.

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:

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:

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

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

Integration setup

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

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

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

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

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

claude

📝 "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"

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?"

Parameters:

• category - Filter by category: base, application, marketing, foundations, shared-assets, examples
• skip - Number of components to skip for pagination (default: 0)
• limit - Maximum number of components to return (default: 100)
• key - API key for authentication

The response includes total, skip, limit, and has_more fields for pagination. For example, to get the second page: list_components({ skip: 100, limit: 100 }).

search_components - Search by functionality

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

Parameters:

• query - Search query (required)
• category_filter - Optional category filter
• limit - Maximum number of results (default: 20)
• key - API key for authentication

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 (PRO only)

"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 (PRO only)

"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)

• Core base UI components (buttons, inputs, forms, select, etc.)
• Core application components (date picker, table, charts, etc.)
• Foundation components (icons, logos)

PRO components (API key required)

• Advanced marketing sections (hero, testimonials, pricing, CTA, etc.)
• Application components (modals, slideout menus, command menus, etc.)
• All page templates and examples (dashboards, landing pages, etc.)
• Shared assets (login, signup, 404 pages, etc.)
• All component variants

With a valid API key, all components are returned. Without a key, only free components are shown. Each component in the response includes an access field ("public" or "pro") so you can see what's available.

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

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:

   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

{
  "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!