OriginUI MCP Server

A Model Context Protocol (MCP) server that provides access to OriginUI components, enabling Claude Code agents to search, browse, and install OriginUI components seamlessly.

Features

• Component Search: Search components by name, category, or tags
• Component Details: Get comprehensive information about specific components
• Installation Commands: Generate proper `pnpm dlx shadcn@latest add` commands
• Visual Previews: Get component screenshots and visual descriptions to assess fit
• Component Preview: View styling information and usage examples
• Category Filtering: Browse components by category (buttons, inputs, forms, etc.)

🚀 Quick Start

TL;DR: Add this to your `~/.claude-code/mcp.json` file:

{
  "mcpServers": {
    "origin-ui": {
      "command": "npx",
      "args": ["--yes", "github:kelvinchng/origin-ui-mcp"],
      "env": {}
    }
  }
}

Restart Claude Code and ask: *"What OriginUI button components are available?"*

Installation

Option 1: Use with npx (Recommended - No Cloning Required!)

No installation needed! You can use the MCP server directly from the GitHub repository with npx.

Option 2: Clone and Build Locally

git clone https://github.com/kelvinchng/origin-ui-mcp.git
cd origin-ui-mcp
npm install
npm run build

Option 3: Global Installation (Coming Soon)

npm install -g origin-ui-mcp

Claude Code Integration

Step 1: Add to Claude Code MCP Configuration

Create or edit your Claude Code MCP configuration file at `~/.claude-code/mcp.json`:

Option A: Using npx (Recommended)

{
  "mcpServers": {
    "origin-ui": {
      "command": "npx",
      "args": ["--yes", "github:kelvinchng/origin-ui-mcp"],
      "env": {}
    }
  }
}

Option B: Using local clone

{
  "mcpServers": {
    "origin-ui": {
      "command": "node",
      "args": ["/absolute/path/to/origin-ui-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Note: With Option A (npx), no manual installation or path configuration is needed!

Step 2: Restart Claude Code

After adding the MCP configuration, restart Claude Code to load the OriginUI MCP server.

Step 3: Verify Integration

You can verify the integration is working by asking Claude Code:

"What OriginUI components are available for buttons?"

Claude Code should now be able to search, describe, and provide installation commands for OriginUI components.

Usage Examples

Once integrated with Claude Code, you can ask questions like:

• "Find me payment-related components"
• "How do I install the button component?"
• "What styling options does the card component have?"
• "Show me all navigation components"
• "I need a component for user input forms"

Claude Code will use the MCP server to provide accurate information and installation commands.

📸 Visual Component Assessment

One of the key features is the ability to get visual previews of components to help LLMs make better recommendations:

"Show me what the payment component looks like"
"Get a screenshot of the button component"
"I want to see the visual style of navigation components"

The MCP server will provide:

• Visual descriptions of component appearance
• Links to live examples on OriginUI
• Theme-specific information (light/dark modes)
• Mobile responsiveness details
• Use case recommendations based on visual style

Available Tools

`search_components`

Search for OriginUI components by name, category, or tags.

Parameters:

• `query` (string, required): Search query
• `category` (string, optional): Filter by category
• `limit` (number, optional): Maximum results (default: 10)

Example:

search_components({
  query: "payment",
  category: "form",
  limit: 5
})

`get_component_details`

Get detailed information about a specific component.

Parameters:

• `componentId` (string, required): Component ID (e.g., "comp-163")

Example:

get_component_details({
  componentId: "comp-163"
})

`list_components`

List all available components with basic information.

Parameters:

• `category` (string, optional): Filter by category
• `limit` (number, optional): Maximum results (default: 50)

`get_install_command`

Get the installation command for a specific component.

Parameters:

• `componentId` (string, required): Component ID

Returns:

pnpm dlx shadcn@latest add https://originui.com/r/comp-163.json

`get_component_preview`

Get component preview with styling information and usage examples.

Parameters:

• `componentId` (string, required): Component ID

`get_component_screenshot`

Get component visual preview to help assess if it fits your project.

Parameters:

• `componentId` (string, required): Component ID
• `theme` (string, optional): Theme preference ("light", "dark", "both")

Returns:

• Visual descriptions of component appearance
• Screenshots when available
• Links to live examples
• Use case recommendations
• Installation instructions

Component Categories

• `button` - Button components
• `input` - Input and form controls
• `select` - Select and dropdown components
• `navbar` - Navigation components
• `card` - Card and container components
• `form` - Form-related components
• `layout` - Layout components
• `navigation` - Navigation elements
• `feedback` - Feedback and status components
• `data-display` - Data display components
• `overlay` - Modal and overlay components
• `typography` - Text and typography components
• `media` - Media components

Example Usage with Claude Code

// Search for button components
const buttons = await search_components({
  query: "button",
  category: "button",
  limit: 10
});

// Get details for a specific component
const details = await get_component_details({
  componentId: "comp-163"
});

// Get installation command
const installCmd = await get_install_command({
  componentId: "comp-163"
});

// Get visual preview to assess fit
const screenshot = await get_component_screenshot({
  componentId: "comp-163",
  theme: "both"
});

// Install the component
// pnpm dlx shadcn@latest add https://originui.com/r/comp-163.json

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Start the MCP server
npm start

How It Works

1. Component Discovery: The server maintains a registry of OriginUI components with metadata

2. Dynamic Fetching: Component details are fetched from OriginUI's JSON registry on demand

3. Caching: Components are cached for 5 minutes to improve performance

4. Installation: Generates proper `pnpm dlx shadcn@latest add` commands with correct URLs

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details.