shadcn/ui MCP

Servidor MCP de Shadcn UI v4

🚀 La forma más rápida de integrar componentes de shadcn/ui en tu flujo de trabajo con IA

Un servidor de Model Context Protocol (MCP) que proporciona a los asistentes de IA acceso completo a los componentes, bloques, demos y metadatos de shadcn/ui v4. Recupera sin problemas implementaciones en React, Svelte, Vue y React Native para tu flujo de trabajo de desarrollo impulsado por IA.

✨ Características principales

• 🎯 Soporte Multi-Framework - Implementaciones en React, Svelte, Vue y React Native
• 📦 Código fuente de componentes - Código TypeScript más reciente de shadcn/ui v4
• 🎨 Demos de componentes - Implementaciones de ejemplo y patrones de uso
• 🏗️ Soporte de bloques - Implementaciones completas de bloques (paneles, calendarios, formularios)
• 📋 Acceso a metadatos - Dependencias, descripciones y detalles de configuración
• 🔍 Exploración de directorios - Explora las estructuras del repositorio
• ⚡ Caché inteligente - Integración eficiente con la API de GitHub y manejo de límites de tasa
• 🌐 Transporte SSE - Soporte de Server-Sent Events para despliegues multi-cliente
• 🐳 Listo para Docker - Contenerización lista para producción con Docker Compose

🚀 Inicio rápido

# Basic usage (60 requests/hour)
npx @jpisnice/shadcn-ui-mcp-server

# With GitHub token (5000 requests/hour) - Recommended
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# Switch frameworks
npx @jpisnice/shadcn-ui-mcp-server --framework svelte
npx @jpisnice/shadcn-ui-mcp-server --framework vue
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

# Use Base UI instead of Radix (React only)
npx @jpisnice/shadcn-ui-mcp-server --ui-library base

🎯 Obtén tu token de GitHub en 2 minutos: docs/getting-started/github-token.md

📦 Instalación con un clic (Claude Desktop)

Descarga y haz doble clic en el archivo .mcpb para una instalación instantánea:

1. Descarga shadcn-ui-mcp-server.mcpb desde Releases
2. Haz doble clic en el archivo - Claude Desktop se abre automáticamente
3. Ingresa tu token de GitHub (opcional, para límites de tasa más altos)
4. Haz clic en Instalar - las herramientas están disponibles de inmediato

Instalación manual: Claude Desktop → Configuración → MCP → Agregar servidor → Explorar → Seleccionar archivo .mcpb

Referencias: Extensiones de escritorio de Anthropic | Construyendo MCPB

🌐 Transporte SSE y despliegue con Docker

Ejecuta el servidor con transporte de Server-Sent Events (SSE) para soporte multi-cliente y despliegues de producción:

Inicio rápido con SSE

# SSE mode (supports multiple concurrent connections)
node build/index.js --mode sse --port 7423

# Docker Compose (production ready)
docker-compose up -d

# Connect with Claude Code
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse

Modos de transporte

• stdio (predeterminado) - Entrada/salida estándar para uso CLI
• sse - Server-Sent Events para conexiones basadas en HTTP
• dual - Tanto stdio como SSE simultáneamente

Ejemplos de Docker

# Basic container
docker run -p 7423:7423 shadcn-ui-mcp-server

# With GitHub API token
docker run -p 7423:7423 -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token shadcn-ui-mcp-server

# Docker Compose (recommended)
docker-compose up -d
curl http://localhost:7423/health

Variables de entorno

• MCP_TRANSPORT_MODE - Modo de transporte (stdio|sse|dual)
• MCP_PORT - Puerto del servidor SSE (predeterminado: 7423 - SHADCN en el teclado numérico)
• MCP_HOST - Enlace de host (predeterminado: 0.0.0.0)
• MCP_CORS_ORIGINS - Orígenes CORS (separados por comas)
• GITHUB_PERSONAL_ACCESS_TOKEN - Token de API de GitHub
• UI_LIBRARY - Biblioteca de primitivas de UI: radix (predeterminado) o base (solo React)

📚 Documentación

Sección	Descripción
🚀 Primeros pasos	Instalación, configuración y primeros pasos
⚙️ Configuración	Selección de framework, tokens y opciones
🔌 Integración	Integraciones con editores y herramientas
📖 Uso	Ejemplos, tutoriales y casos de uso
🎨 Frameworks	Documentación específica por framework
🐛 Solución de problemas	Problemas comunes y soluciones
🔧 Referencia de API	Referencia de herramientas y detalles técnicos

🎨 Soporte de frameworks

Este servidor MCP admite cuatro implementaciones populares de shadcn:

Framework	Repositorio	Mantenedor	Descripción
React (predeterminado)	shadcn/ui	shadcn	Componentes React de shadcn/ui v4
Svelte	shadcn-svelte	huntabyte	Componentes Svelte de shadcn-svelte
Vue	shadcn-vue	unovue	Componentes Vue de shadcn-vue
React Native	react-native-reusables	Founded Labs	Componentes React Native de react-native-reusables

Biblioteca de UI (solo React)

shadcn/ui v4 admite dos bibliotecas de primitivas para React: Radix UI (predeterminado) y Base UI.

# Radix UI (default)
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library radix

# Base UI
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library base

# Or via environment variable
UI_LIBRARY=base npx @jpisnice/shadcn-ui-mcp-server

Ejemplo de configuración de Claude Desktop:

{
  "args": ["--framework", "react", "--ui-library", "base"]
}

🛠️ Configuración esencial

1. Obtén el token de GitHub (recomendado)

# Visit: https://github.com/settings/tokens
# Generate token with no scopes needed
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

2. Ejecuta el servidor

# React (default)
npx @jpisnice/shadcn-ui-mcp-server

# Svelte
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Vue  
npx @jpisnice/shadcn-ui-mcp-server --framework vue

# React Native
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

3. Integra con tu editor

• Claude Code: Consulta Integración con Claude Code a continuación
• VS Code: docs/integration/vscode.md
• Cursor: docs/integration/cursor.md
• Claude Desktop: docs/integration/claude-desktop.md
• Continue.dev: docs/integration/continue.md

💻 Integración con Claude Code

Adición rápida (CLI)

# Add the shadcn-ui MCP server
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN

Transporte SSE

Para despliegues de producción con transporte SSE:

# Start server in SSE mode
node build/index.js --mode sse --port 7423

# Connect with Claude Code
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse

Comandos específicos por framework

Consulta la Guía de integración con Claude Code para comandos específicos por framework (React, Svelte, Vue, React Native).

Referencia: Documentación de MCP de Claude Code

🎯 Casos de uso

• Desarrollo impulsado por IA - Permite que los asistentes de IA construyan interfaces con shadcn/ui
• Despliegues multi-cliente - El transporte SSE admite múltiples conexiones concurrentes
• Entornos de producción - Listo para Docker Compose con verificaciones de salud y monitoreo
• Descubrimiento de componentes - Explora los componentes disponibles y su uso
• Aprendizaje multi-framework - Compara implementaciones en React, Svelte, Vue y React Native
• Prototipado rápido - Obtén implementaciones completas de bloques para paneles, formularios, etc.
• Generación de código - Genera código de componentes con las dependencias adecuadas

📦 Instalación

# Global installation (optional)
npm install -g @jpisnice/shadcn-ui-mcp-server

# Or use npx (recommended)
npx @jpisnice/shadcn-ui-mcp-server

🔨 Compilación desde el código fuente

Requisitos previos

• Node.js >= 18.0.0
• npm o pnpm

Pasos de compilación

# Clone the repository
git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git
cd shadcn-ui-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node build/index.js --github-api-key YOUR_TOKEN

Ejecución local

# After building, run with options
node build/index.js --github-api-key YOUR_TOKEN
node build/index.js --framework svelte

Compilación del paquete MCPB

El proyecto incluye un manifest.json siguiendo la especificación MCPB. El archivo .mcpb es un archivo ZIP que contiene el servidor, las dependencias y la configuración.

Consulta CONTRIBUTING.md para obtener instrucciones detalladas de empaquetado.

Referencia: Construyendo extensiones de escritorio con MCPB

🔗 Enlaces rápidos

• 📖 Documentación completa
• 🚀 Guía de primeros pasos
• 🌐 Guía de transporte SSE y Docker
• 🎨 Comparación de frameworks
• 🔧 Referencia de API
• 🐛 Solución de problemas
• 💬 Problemas y discusiones

📄 Licencia

Licencia MIT - consulta LICENSE para más detalles.

🙏 Agradecimientos

• shadcn - Por la increíble biblioteca de componentes de UI para React
• huntabyte - Por la excelente implementación en Svelte
• unovue - Por la completa implementación en Vue
• Founded Labs - Por la implementación en React Native
• Anthropic - Por la especificación de Model Context Protocol

---

Hecho con ❤️ por Janardhan Polle

¡Dale una estrella ⭐ a este repositorio si te resulta útil!