shadcn-mcp

shadcn-mcp

An advanced MCP (Model Context Protocol) server for shadcn/ui component references. This server provides AI assistants like Claude with detailed, structured information about shadcn/ui components to help developers implement them correctly.

Features

• Rich Component Library: Access to all shadcn/ui components with code, usage examples, and documentation
• Enhanced Search: Find components by name, feature, category, or functionality
• Component Composition Patterns: See how different components work together in common UI patterns
• Migration Guides: Help with upgrading to React 19 and Tailwind CSS v4
• Best Practices: Coding standards and patterns for shadcn/ui development
• Theme Customization: Examples of how to customize components for different design systems
• Accessibility Information: WCAG compliance levels and accessibility considerations for each component
• Responsive Examples: See how components adapt to different screen sizes
• Analytics: Track which components are most frequently requested
• Validation: Validate components against shadcn/ui best practices
• GitHub Synchronization: Keep components up-to-date with the latest shadcn/ui releases
• Filesystem Storage: Easy to manage and extend component library

Installation

# Install globally
npm install -g shadcn-mcp

# Or run with npx (no installation required)
npx shadcn-mcp

Development

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

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (runs on port 3176 by default)
npm start

# Start in development mode (auto-restart on changes)
npm run watch

# Test with the inspector
npm run inspector

Commands

• npm start - Start the MCP server
• npm run dev - Start the server in development mode
• npm run watch - Start the server with auto-restart on file changes
• npm run build - Build the TypeScript project
• npm run inspector - Test the MCP server with the inspector utility
• npm run sync - Synchronize components from shadcn/ui GitHub repository
• npm run validate - Run component validation tool
• npm run analytics - View component query analytics
• npm run add-component - Add a new component interactively

Adding Custom Components

Use the interactive component adding tool:

npm run add-component

Or manually add a JSON file to the data/components directory following this structure:

{
  "name": "ComponentName",
  "description": "Description of the component",
  "code": "// Full component code here",
  "usage": "<ComponentName>Example usage</ComponentName>",
  "version": "1.0.0",
  "lastUpdated": "2025-05-16T12:00:00Z",
  "props": {
    "propName": {
      "type": "string",
      "description": "Description of the prop",
      "required": false,
      "default": "Default value"
    }
  },
  "importStatement": "import { ComponentName } from \"@/components/ui/component-name\"",
  "dependencies": ["package-name"],
  "examples": [
    {
      "name": "Example name",
      "code": "<ComponentName>Example code</ComponentName>",
      "description": "Example description"
    }
  ],
  "compositionPatterns": [
    {
      "name": "Pattern name",
      "description": "Pattern description",
      "code": "// Example code using multiple components",
      "components": ["ComponentName", "AnotherComponent"]
    }
  ],
  "themeCustomization": {
    "cssVariables": "--component-bg: oklch(var(--p));",
    "tailwindConfig": "theme: { extend: {...} }",
    "examples": [
      {
        "name": "Custom theme",
        "description": "Theme description",
        "code": ":root { ... }"
      }
    ]
  },
  "responsiveExamples": [
    {
      "breakpoint": "sm",
      "description": "Mobile layout",
      "code": "<div className=\"sm:flex\">...</div>"
    }
  ],
  "accessibility": {
    "wcagLevel": "AA",
    "considerations": ["Keyboard navigable", "Screen reader support"]
  },
  "features": ["feature1", "feature2"],
  "category": "Input",
  "relatedComponents": ["RelatedComponent"]
}

Configuration

Port Configuration

By default, the server runs on port 3176 to avoid conflicts with common development tools like Next.js. You can customize the port using an environment variable:

# Run on a custom port
PORT=4567 npm start

Claude Desktop

Add to your .claude.json configuration file (usually in your home directory):

{
  "mcpServers": {
    "shadcn-ui-server": {
      "command": "npx",
      "args": ["-y", "shadcn-mcp"]
    }
  }
}

Cursor

Add to your configuration:

{
  "mcpServers": {
    "shadcn-ui-server": {
      "command": "npx",
      "args": ["-y", "shadcn-mcp"]
    }
  }
}

API Endpoints

All endpoints are available at http://localhost:3176 by default:

• POST /mcp/v1/components - Search for components

  • Body: { "query": "button" }
  • Returns: { "components": [...] }

• GET /mcp/v1/components/:id - Get component by ID/name

  • Returns: { "component": {...} }

• POST /mcp/v1/validate - Validate component code

  • Body: { "code": "// Component code" }
  • Returns: { "results": { "valid": true, "errors": [], "warnings": [], "suggestions": [] } }

• GET /mcp/v1/analytics - Get component query analytics

  • Returns: { "stats": { "topQueries": [...], "totalQueries": 100 } }

• GET /mcp/v1/categories - Get component categories

  • Returns: { "categories": ["Input", "Display", ...] }

• GET /mcp/v1/categories/:category - Get components by category

  • Returns: { "components": [...] }

• GET /mcp/v1/patterns - Get component patterns

  • Query: ?category=Form (optional)
  • Returns: { "patterns": [...] }

• GET /mcp/v1/patterns/:name - Get pattern by name

  • Returns: { "pattern": {...} }

• GET /mcp/v1/migrations - Get migrations

  • Returns: { "migrations": [...] }

• GET /mcp/v1/migrations/:id - Get migration by ID

  • Returns: { "migration": {...} }

• GET /mcp/v1/best-practices - Get best practices

  • Query: ?category=Styling (optional)
  • Returns: { "bestPractices": [...] }

• GET /mcp/v1/best-practices/:id - Get best practice by ID

  • Returns: { "bestPractice": {...} }

• GET /health - Health check endpoint

  • Returns: { "status": "healthy", "version": "1.2.0" }

Usage Examples with Claude

Here are some examples of how to use the shadcn-ui MCP with Claude:

• Basic component request: "Show me the shadcn/ui Button component"
• Feature search: "Which shadcn/ui components are good for form validation?"
• Composition request: "How do I create a form with shadcn/ui components?"
• Migration help: "How do I update my shadcn/ui components for React 19?"
• Best practices: "What are the best practices for creating shadcn/ui components?"
• Theme customization: "How can I change the colors of shadcn/ui components?"
• Accessibility query: "What accessibility considerations do I need for the Dialog component?"
• Responsive design: "How do I make the Card component responsive?"

The enhanced MCP features particularly benefit Claude Code, enabling it to generate better quality components that follow shadcn/ui patterns and best practices.

License

MIT