Radix UI MCP Server

A lightweight Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to Radix UI libraries including Themes, Primitives, and Colors. This server enables AI tools like Claude Desktop, Continue.dev, VS Code, Cursor, and other MCP-compatible clients to retrieve and work with Radix UI components seamlessly.

Built upon the excellent foundation of shadcn-ui-mcp-server by @Jpisnice. This project adapts that work to focus specifically on the Radix UI ecosystem while maintaining the same powerful MCP integration capabilities.

🚀 Key Features

• Radix Themes: Access high-level styled components with built-in design system
• Radix Primitives: Get unstyled, accessible component implementations
• Radix Colors: Retrieve semantic color scales with light/dark mode support
• Component Source Code: Get the latest Radix UI component TypeScript source
• Installation Guides: Dynamic installation instructions for all package managers
• GitHub API Integration: Intelligent caching with p-memoize and respectful rate limiting
• Lightweight: Built with modern Sindre Sorhus packages (ky, p-limit, p-memoize) for minimal bundle size

📦 Quick Start

⚡ Using npx (Recommended)

The fastest way to get started - no installation required!

# Basic usage (rate limited to 60 requests/hour)
npx @gianpieropuleo/radix-mcp-server@latest

# With GitHub token for better rate limits (5000 requests/hour)
npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here

# Short form
npx @gianpieropuleo/radix-mcp-server@latest -g ghp_your_token_here

# Using environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @gianpieropuleo/radix-mcp-server@latest

# Select specific library
npx @gianpieropuleo/radix-mcp-server@latest --library themes
npx @gianpieropuleo/radix-mcp-server@latest --library primitives
npx @gianpieropuleo/radix-mcp-server@latest --library colors

# All libraries (default)
npx @gianpieropuleo/radix-mcp-server@latest --library all

# Using environment variable for library
export RADIX_LIBRARY=themes
npx @gianpieropuleo/radix-mcp-server@latest

🎯 Try it now: Run npx @gianpieropuleo/radix-mcp-server@latest --help to see all options!

🔧 Command Line Options

radix-mcp-server [options]

Options:
  --library, -l <library>         Radix library: 'themes', 'primitives', 'colors', or 'all' (default: all)
  --github-api-key, -g <token>    GitHub Personal Access Token for API access
  --help, -h                      Show this help message
  --version, -v                   Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN    Alternative way to provide GitHub token
  RADIX_LIBRARY                   Library to use: 'themes', 'primitives', 'colors', or 'all' (default: all)
  LOG_LEVEL                       Log level (debug, info, warn, error) - default: info

Examples:
  npx @gianpieropuleo/radix-mcp-server@latest
  npx @gianpieropuleo/radix-mcp-server@latest --library themes
  npx @gianpieropuleo/radix-mcp-server@latest --library primitives --github-api-key ghp_your_token_here
  npx @gianpieropuleo/radix-mcp-server@latest -l colors -g ghp_your_token_here
  npx @gianpieropuleo/radix-mcp-server@latest -l all

🎨 Radix UI Libraries

🎭 Radix Themes

High-level React components with a built-in design system. Perfect for rapid application development.

// Example: Get Button component from Themes
{
  "tool": "themes_get_component_source",
  "arguments": { "componentName": "button" }
}

🧩 Radix Primitives

Low-level, unstyled, accessible React components. Maximum flexibility for custom designs.

// Example: Get Dialog primitive
{
  "tool": "primitives_get_component_source",
  "arguments": { "componentName": "dialog" }
}

🌈 Radix Colors

Beautiful, accessible color scales with semantic meanings and dark mode support.

// Example: List all color scales
{
  "tool": "colors_list_scales",
  "arguments": {}
}

🔑 GitHub API Token Setup

Why do you need a token?

• Without token: Limited to 60 API requests per hour
• With token: Up to 5,000 requests per hour
• Better reliability and faster responses

📝 Getting Your Token (2 minutes)

1. Go to GitHub Settings:

   • Visit GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   • Or: GitHub Profile → Settings → Developer settings → Personal access tokens

2. Generate New Token:

   • Click "Generate new token (classic)"
   • Add a note: "Radix UI MCP server"
   • Expiration: Choose your preference (90 days recommended)
   • Scopes: ✅ No scopes needed! (public repository access is sufficient)

3. Copy Your Token:

   • Copy the generated token (starts with ghp_)
   • ⚠️ Save it securely - you won't see it again!

🚀 Using Your Token

Method 1: Command Line (Quick testing)

npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here

Method 2: Environment Variable (Recommended)

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Then simply run:
npx @gianpieropuleo/radix-mcp-server@latest

🛠️ Editor Integration

Claude Desktop Integration

Add to your Claude Desktop configuration (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": [
        "@gianpieropuleo/radix-mcp-server@latest",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // Or for specific library only:
    "radix-themes": {
      "command": "npx",
      "args": [
        "@gianpieropuleo/radix-mcp-server@latest",
        "--library",
        "themes",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

Or with environment variable:

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

VS Code Integration

Method 1: Using Continue Extension

{
  "continue.server": {
    "mcpServers": {
      "radix-ui": {
        "command": "npx",
        "args": [
          "@gianpieropuleo/radix-mcp-server@latest",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      }
    }
  }
}

Method 2: Using Claude Extension

{
  "claude.mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Cursor Integration

Create a .cursorrules file in your project root:

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

🎯 Usage Examples

Getting Radix Themes Components

Ask your AI assistant:

"Show me the source code for the Radix Themes Button component"
"List all available Radix Themes components"
"How do I install and set up Radix Themes?"

Working with Radix Primitives

Ask your AI assistant:

"Get the Dialog primitive from Radix UI"
"Show me how to use the Accordion primitive"
"List all available Radix Primitives"

Using Radix Colors

Ask your AI assistant:

"Show me the blue color scale from Radix Colors"
"How do I set up Radix Colors with CSS variables?"
"List all available color scales"

Building a Complete UI

Ask your AI assistant:

"Create a dashboard using Radix Themes components"
"Build a modal dialog using Radix Primitives"
"Set up a design system with Radix Colors"

🛠️ Available Tools

The MCP server provides these tools for AI assistants:

Radix Themes Tools

• themes_list_components - List all available Radix Themes components
• themes_get_component_source - Get Radix Themes component source code
• themes_get_component_documentation - Get Radix Themes component documentation
• themes_get_getting_started - Get installation instructions for Radix Themes

Radix Primitives Tools

• primitives_list_components - List all available Radix Primitives
• primitives_get_component_source - Get Radix Primitive component source code
• primitives_get_component_documentation - Get Radix Primitive component documentation
• primitives_get_getting_started - Get installation instructions for Radix Primitives

Radix Colors Tools

• colors_list_scales - List all available color scales
• colors_get_scale - Get specific color scale definition
• colors_get_scale_documentation - Get Radix Colors documentation
• colors_get_getting_started - Get installation instructions for Radix Colors

Example Tool Usage

// Get Radix Themes Button component
{
  "tool": "themes_get_component_source",
  "arguments": { "componentName": "button" }
}

// List all Radix Primitives
{
  "tool": "primitives_list_components",
  "arguments": {}
}

// Get blue color scale
{
  "tool": "colors_get_scale",
  "arguments": { "scaleName": "blue" }
}

// Get installation guide for Radix Colors
{
  "tool": "colors_get_getting_started",
  "arguments": {}
}

⚡ Architecture & Performance

Modern, Lightweight Stack

This MCP server is built with a carefully curated set of modern, lightweight packages:

• ky - Elegant HTTP client (replaces heavier alternatives)
• p-limit - Concurrency control for respectful API usage
• p-memoize - Intelligent function memoization with TTL
• expiry-map - TTL cache support for automatic expiration
• pino - Fast, structured logging
• zod - Runtime type validation

Smart Caching Strategy

• 24-hour TTL: All GitHub API responses are cached for 24 hours
• Function-level memoization: Each API function is individually memoized
• Automatic expiration: Cache entries expire automatically, preventing stale data
• Memory efficient: Only active data is kept in memory

Rate Limiting & API Respect

• Concurrency control: Maximum 1 concurrent request to GitHub API
• Intelligent batching: Related requests are batched when possible
• Graceful degradation: Fallback to cached data when rate limits hit
• Token support: GitHub tokens increase limits from 60 to 5,000 requests/hour

🐛 Troubleshooting

Common Issues

"Rate limit exceeded" errors:

# Solution: Add GitHub API token
npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token_here

"Command not found" errors:

# Solution: Install Node.js 18+ and ensure npx is available
node --version  # Should be 18+
npx --version   # Should work

Component not found:

# Check available components first
npx @gianpieropuleo/radix-mcp-server --library themes
# Then call appropriate list tool via your MCP client

Library selection issues:

# Verify library parameter
npx @gianpieropuleo/radix-mcp-server --library themes  # ✅ Valid
npx @gianpieropuleo/radix-mcp-server --library invalid # ❌ Invalid

Debug Mode

Enable verbose logging:

# Set debug environment variable
LOG_LEVEL=debug npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation
• 📦 npm Package

🔗 Related Projects

• Radix UI Themes - High-level React components
• Radix UI Primitives - Low-level React components
• Radix UI Colors - Beautiful color system
• Model Context Protocol - The protocol specification
• MCP TypeScript SDK - Official MCP SDK

⭐ Acknowledgments

• Radix UI Team for the amazing component libraries
• Anthropic for the Model Context Protocol specification
• The open source community for inspiration and contributions

Made with ❤️ by Gianpiero Puleo and Claude Code

Built upon the excellent work of shadcn-ui-mcp-server by @Jpisnice

Star ⭐ this repo if you find it helpful! Also consider starring the original project that made this possible.