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

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

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.

Prerequisites

Before integrating the MCP server, ensure you have:

• Claude Code, Cursor, Codex, Gemini CLI, or OpenCode 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"

Replace YOUR_API_KEY with your actual 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 mcp list

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

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.

Search and discovery

search_components — find any component using natural language

This is the primary search tool. It uses multimodal AI embeddings trained on both the text description and screenshot of every component. Describe what you need in plain language — the search understands visual concepts like "split layout", "testimonial quote", or "dark background" and matches them to the right components.

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

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

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

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!