A mcp server to allow LLMS gain context about shadcn ui component structure,usage and installation
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to shadcn/ui v4 components, blocks, demos, and metadata. This server enables AI tools like Claude Desktop, Continue.dev, and other MCP-compatible clients to retrieve and work with shadcn/ui components seamlessly.
The fastest way to get started - no installation required!
# Basic usage (rate limited to 60 requests/hour)
npx @jpisnice/shadcn-ui-mcp-server
# With GitHub token for better rate limits (5000 requests/hour)
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
# Short form
npx @jpisnice/shadcn-ui-mcp-server -g ghp_your_token_here
# Using environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @jpisnice/shadcn-ui-mcp-server
๐ฏ Try it now: Run npx @jpisnice/shadcn-ui-mcp-server --help
to see all options!
shadcn-ui-mcp-server [options]
Options:
--github-api-key, -g <token> GitHub Personal Access Token
--help, -h Show help message
--version, -v Show version information
Environment Variables:
GITHUB_PERSONAL_ACCESS_TOKEN Alternative way to provide GitHub token
Examples:
npx @jpisnice/shadcn-ui-mcp-server --help
npx @jpisnice/shadcn-ui-mcp-server --version
npx @jpisnice/shadcn-ui-mcp-server -g ghp_1234567890abcdef
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token npx @jpisnice/shadcn-ui-mcp-server
Why do you need a token?
Go to GitHub Settings:
Generate New Token:
Copy Your Token:
ghp_
)Method 1: Command Line (Quick testing)
npx @jpisnice/shadcn-ui-mcp-server --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 @jpisnice/shadcn-ui-mcp-server
Method 3: Claude Desktop Configuration
{
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
# Test without token (should show rate limit warning)
npx @jpisnice/shadcn-ui-mcp-server --help
# Test with token (should show success message)
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token --help
# Check your current rate limit
curl -H "Authorization: token ghp_your_token" https://api.github.com/rate_limit
The MCP server provides these tools for AI assistants:
get_component
- Get component source codeget_component_demo
- Get component usage exampleslist_components
- List all available componentsget_component_metadata
- Get component dependencies and infoget_block
- Get complete block implementations (dashboard-01, calendar-01, etc.)list_blocks
- List all available blocks with categoriesget_directory_structure
- Explore the shadcn/ui repository structure// These tools can be called by AI assistants via MCP protocol
// Get button component source
{
"tool": "get_component",
"arguments": { "componentName": "button" }
}
// List all components
{
"tool": "list_components",
"arguments": {}
}
// Get dashboard block
{
"tool": "get_block",
"arguments": { "blockName": "dashboard-01" }
}
Add to your Claude Desktop configuration (~/.config/Claude/claude_desktop_config.json
):
{
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
}
}
}
Or with environment variable:
{
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@jpisnice/shadcn-ui-mcp-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
"Rate limit exceeded" errors:
# Solution: Add GitHub API token
npx @jpisnice/shadcn-ui-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 @jpisnice/shadcn-ui-mcp-server
# Then call list_components tool via your MCP client
Network/proxy issues:
# Set proxy if needed
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
npx @jpisnice/shadcn-ui-mcp-server
Enable verbose logging:
# Set debug environment variable
DEBUG=* npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token
This project is licensed under the MIT License - see the LICENSE file for details.
git checkout -b feature/amazing-feature
)git commit -m 'Add amazing feature'
)git push origin feature/amazing-feature
)Made with โค๏ธ by Janardhan Polle
Star โญ this repo if you find it helpful!
{ "mcpServers": { "shadcn-ui-mcp-server": { "command": "npx", "args": [ "@jpisnice/shadcn-ui-mcp-server" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories