Content
# Radix UI MCP Server
[](https://badge.fury.io/js/@gianpieropuleo%2Fradix-mcp-server)
[](https://opensource.org/licenses/MIT)
A lightweight Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to [Radix UI](https://www.radix-ui.com/) 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](https://github.com/Jpisnice/shadcn-ui-mcp-server) by [@Jpisnice](https://github.com/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!
```bash
# 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
```bash
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.
```typescript
// 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.
```typescript
// 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.
```typescript
// 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)](https://github.com/settings/tokens)
- 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)**
```bash
npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here
```
**Method 2: Environment Variable (Recommended)**
```bash
# 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`):
```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:
```json
{
"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
```json
{
"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
```json
{
"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:
```json
{
"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
```typescript
// 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](https://github.com/sindresorhus/ky)** - Elegant HTTP client (replaces heavier alternatives)
- **[p-limit](https://github.com/sindresorhus/p-limit)** - Concurrency control for respectful API usage
- **[p-memoize](https://github.com/sindresorhus/p-memoize)** - Intelligent function memoization with TTL
- **[expiry-map](https://github.com/sindresorhus/expiry-map)** - TTL cache support for automatic expiration
- **[pino](https://github.com/pinojs/pino)** - Fast, structured logging
- **[zod](https://github.com/colinhacks/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:**
```bash
# Solution: Add GitHub API token
npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token_here
```
**"Command not found" errors:**
```bash
# Solution: Install Node.js 18+ and ensure npx is available
node --version # Should be 18+
npx --version # Should work
```
**Component not found:**
```bash
# Check available components first
npx @gianpieropuleo/radix-mcp-server --library themes
# Then call appropriate list tool via your MCP client
```
**Library selection issues:**
```bash
# Verify library parameter
npx @gianpieropuleo/radix-mcp-server --library themes # ✅ Valid
npx @gianpieropuleo/radix-mcp-server --library invalid # ❌ Invalid
```
### Debug Mode
Enable verbose logging:
```bash
# 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](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](https://github.com/gianpieropuleo/radix-mcp-server/issues)
- 💬 [Discussions](https://github.com/gianpieropuleo/radix-mcp-server/discussions)
- 📖 [Documentation](https://github.com/gianpieropuleo/radix-mcp-server#readme)
- 📦 [npm Package](https://www.npmjs.com/package/@gianpieropuleo/radix-mcp-server)
## 🔗 Related Projects
- [Radix UI Themes](https://www.radix-ui.com/themes) - High-level React components
- [Radix UI Primitives](https://www.radix-ui.com/primitives) - Low-level React components
- [Radix UI Colors](https://www.radix-ui.com/colors) - Beautiful color system
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP SDK
## ⭐ Acknowledgments
- [Radix UI Team](https://github.com/radix-ui) for the amazing component libraries
- [Anthropic](https://anthropic.com) for the Model Context Protocol specification
- The open source community for inspiration and contributions
---
**Made with ❤️ by [Gianpiero Puleo](https://github.com/gianpieropuleo) and [Claude Code](https://www.anthropic.com/claude-code)**
**Built upon the excellent work of [shadcn-ui-mcp-server](https://github.com/Jpisnice/shadcn-ui-mcp-server) by [@Jpisnice](https://github.com/Jpisnice)**
**Star ⭐ this repo if you find it helpful! Also consider starring the [original project](https://github.com/Jpisnice/shadcn-ui-mcp-server) that made this possible.**
Connection Info
You Might Also Like
No recommendations available