What is Shadcn Ui Mcp Unofficial

shadcn-ui-mcp-unofficial is a TypeScript implementation of a Model Context Protocol (MCP) server designed to facilitate AI assistants in accessing and working with shadcn/ui components. It acts as a bridge between AI models and shadcn/ui, allowing for the retrieval of component source code, demos, and installation guides.

Use cases

Use cases for shadcn-ui-mcp-unofficial include enabling AI assistants to fetch and display shadcn/ui component information, assisting developers in understanding component usage, and automating the installation process for shadcn/ui components.

How to use

To use shadcn-ui-mcp-unofficial, first ensure you have Node.js (v18 or later) and npm installed. Install the project dependencies using ‘npm install’. Then, run the server using the provided startup script with ‘bash startup.sh’ or execute the individual commands to clean, build, and start the server.

Key features

Key features of shadcn-ui-mcp-unofficial include tools for retrieving component source code, obtaining demo code and usage examples, generating installation instructions, and providing framework-specific installation guides.

Where to use

shadcn-ui-mcp-unofficial can be used in various fields such as web development, AI assistant development, and component-based UI design, where integration with shadcn/ui components is required.

Shadcn UI v4 MCP Server

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.

🚀 Key Features

• Component Source Code: Get the latest shadcn/ui v4 component TypeScript source
• Component Demos: Access example implementations and usage patterns
• Blocks Support: Retrieve complete block implementations (dashboards, calendars, login forms, etc.)
• Metadata Access: Get component dependencies, descriptions, and configuration details
• Directory Browsing: Explore the shadcn/ui repository structure
• GitHub API Integration: Efficient caching and intelligent rate limit handling

📦 Quick Start

⚡ Using npx (Recommended)

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!

🔧 Command Line 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

🔑 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)
   • Or: GitHub Profile → Settings → Developer settings → Personal access tokens

2. Generate New Token:

   • Click “Generate new token (classic)”
   • Add a note: “shadcn-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)

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"
      }
    }
  }
}

✅ Verify Your Setup

# 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

🛠️ Available Tools

The MCP server provides these tools for AI assistants:

Component Tools

• get_component - Get component source code
• get_component_demo - Get component usage examples
• list_components - List all available components
• get_component_metadata - Get component dependencies and info

Block Tools

• get_block - Get complete block implementations (dashboard-01, calendar-01, etc.)
• list_blocks - List all available blocks with categories

Repository Tools

• get_directory_structure - Explore the shadcn/ui repository structure

Example Tool Usage

// 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" }
}

🔗 Claude Desktop Integration

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"
      }
    }
  }
}

🐛 Troubleshooting

Common Issues

“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

Debug Mode

Enable verbose logging:

# Set debug environment variable
DEBUG=* npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token

📄 License

This project is licensed under the MIT License - see the 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
• 💬 Discussions
• 📖 Documentation
• 📦 npm Package

🔗 Related Projects

• shadcn/ui - The component library this server provides access to
• Model Context Protocol - The protocol specification
• MCP TypeScript SDK - Official MCP SDK

⭐ Acknowledgments

• shadcn for the amazing UI component library
• Anthropic for the Model Context Protocol specification
• The open source community for inspiration and contributions

Made with ❤️ by Janardhan Polle

Star ⭐ this repo if you find it helpful!