MCP server for shadcn/ui component references
npm install shadcn-mcpAn 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.
- 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
``bashInstall globally
npm install -g shadcn-mcp
Development
bash
Clone the repository
git clone https://github.com/yourusername/shadcn-mcp.git
cd shadcn-mcpInstall dependencies
npm installBuild the project
npm run buildStart the server (runs on port 3176 by default)
npm startStart in development mode (auto-restart on changes)
npm run watchTest with the inspector
npm run inspector
`Commands
-
- 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 interactivelyAdding Custom Components
Use the interactive component adding tool:
`bash
npm run add-component
`Or manually add a JSON file to the
directory following this structure:`json
{
"name": "ComponentName",
"description": "Description of the component",
"code": "// Full component code here",
"usage": "Example usage ",
"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": "Example code ",
"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": "..."
}
],
"accessibility": {
"wcagLevel": "AA",
"considerations": ["Keyboard navigable", "Screen reader support"]
},
"features": ["feature1", "feature2"],
"category": "Input",
"relatedComponents": ["RelatedComponent"]
}
`Configuration
$3
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:
bash
Run on a custom port
PORT=4567 npm start
`$3
Add to your
configuration file (usually in your home directory):`json
{
"mcpServers": {
"shadcn-ui-server": {
"command": "npx",
"args": ["-y", "shadcn-mcp"]
}
}
}
`$3
Add to your configuration:
json
{
"mcpServers": {
"shadcn-ui-server": {
"command": "npx",
"args": ["-y", "shadcn-mcp"]
}
}
}
`API Endpoints
All endpoints are available at
by default:-
POST /mcp/v1/components - Search for components
- Body: { "query": "button" }
- Returns: -
- Get component by ID/name
- Returns: { "component": {...} }-
- Validate component code
- Body: { "code": "// Component code" }
- Returns: -
- Get component query analytics
- Returns: { "stats": { "topQueries": [...], "totalQueries": 100 } }-
- Get component categories
- Returns: { "categories": ["Input", "Display", ...] }-
- Get components by category
- Returns: { "components": [...] }-
- Get component patterns
- Query: ?category=Form (optional)
- Returns: { "patterns": [...] }-
- Get pattern by name
- Returns: { "pattern": {...} }-
- Get migrations
- Returns: { "migrations": [...] }-
- Get migration by ID
- Returns: { "migration": {...} }-
- Get best practices
- Query: ?category=Styling (optional)
- Returns: { "bestPractices": [...] }-
- Get best practice by ID
- Returns: { "bestPractice": {...} }-
- Health check endpoint
- Returns: { "status": "healthy", "version": "1.2.0" }`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.
MIT