shadcn-ui-mcp-server by anillahane - MCP Server

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, VS Code, Cursor, 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
Framework Support: Switch between React (shadcn/ui),Vue (shadcn-vue) or Svelte (shadcn-svelte) implementations

📦 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

# Switch to Svelte framework (default is react)
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Use Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here

# Switch to Vue framework with GitHub token (default is react)
npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key ghp_your_token_here
# Using environment variable for framework
export FRAMEWORK=svelte
npx @jpisnice/shadcn-ui-mcp-server

# Or use Vue
export FRAMEWORK=vue
npx @jpisnice/shadcn-ui-mcp-server

🎯 Try it now: Run npx @jpisnice/shadcn-ui-mcp-server --help to see all options!

🔄 Framework Selection: The server supports React (shadcn/ui), Svelte (shadcn-svelte), and Vue (shadcn-vue) implementations. Use --framework svelte or --framework vue to switch frameworks.

🔧 Command Line Options

shadcn-ui-mcp-server [options]

Options:
  --github-api-key, -g <token>    GitHub Personal Access Token
  --framework, -f <framework>     Framework to use: 'react', 'svelte' or 'vue' (default: react)
  --help, -h                      Show help message
  --version, -v                   Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN    Alternative way to provide GitHub token
  FRAMEWORK                       Framework to use: 'react', 'svelte' or 'vue' (default: react)

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
  npx @jpisnice/shadcn-ui-mcp-server --framework svelte
  npx @jpisnice/shadcn-ui-mcp-server -f react
  export FRAMEWORK=svelte && 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)

Go to GitHub Settings:
- Visit GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Or: GitHub Profile → Settings → Developer settings → Personal access tokens
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)
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

🔄 Framework Selection

The MCP server supports both React (shadcn/ui) and Svelte (shadcn-svelte) implementations. You can switch between them based on your project needs.

📋 Framework Comparison

Framework	Repository	File Extension	Description
React (default)	`shadcn-ui/ui`	`.tsx`	React components from shadcn/ui v4
Svelte	`huntabyte/shadcn-svelte`	`.svelte`	Svelte components from shadcn-svelte
Vue	`unovue/shadcn-vue`	`.vue`	Vue components from shadcn-vue

🎯 How to Switch Frameworks

Method 1: Command Line Argument (Recommended)

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

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

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

# Switch back to React
npx @jpisnice/shadcn-ui-mcp-server --framework react
npx @jpisnice/shadcn-ui-mcp-server -f react

Method 2: Environment Variable

# Use Svelte
export FRAMEWORK=svelte
npx @jpisnice/shadcn-ui-mcp-server

# Use React
export FRAMEWORK=react
npx @jpisnice/shadcn-ui-mcp-server

# Use Vue
export FRAMEWORK=vue
npx @jpisnice/shadcn-ui-mcp-server

# Or set for single command
FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server
FRAMEWORK=vue npx @jpisnice/shadcn-ui-mcp-server

Method 3: Combined with GitHub Token

# Svelte with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key ghp_your_token_here

# React with GitHub token (default)
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# Vue with GitHub token
npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key ghp_your_token_here

🔍 Framework Detection

The server will log which framework is being used:

INFO: Framework set to 'svelte' via command line argument
INFO: MCP Server configured for SVELTE framework
INFO: Repository: huntabyte/shadcn-svelte
INFO: File extension: .svelte

INFO: Framework set to 'vue' via command line argument
INFO: MCP Server configured for VUE framework
INFO: Repository: unovue/shadcn-vue
INFO: File extension: .vue

⚠️ Important: When using environment variables, make sure to use the correct syntax:

✅ Correct: export FRAMEWORK=svelte && npx @jpisnice/shadcn-ui-mcp-server
✅ Correct: FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server
❌ Incorrect: FRAMEWORK=svelte npx @jpisnice/shadcn-ui-mcp-server (without proper spacing)

💡 Use Cases

React Projects: Use default or --framework react for React/Next.js applications
Svelte Projects: Use --framework svelte for Svelte/SvelteKit applications
Vue Projects: Use --framework vue for Vue/Nuxt applications
Multi-Framework Development: Switch between frameworks to compare implementations
Learning: Explore React, Svelte, and Vue versions of the same components

🛠️ Editor Integration

VS Code Integration

Method 1: Using Continue Extension

Install Continue Extension:
- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "Continue" and install it
Configure MCP Server:
- Open Command Palette (Ctrl+Shift+P)
- Type "Continue: Configure" and select it
- Add this configuration to your settings:

{
  "continue.server": {
    "mcpServers": {
      "shadcn-ui": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      },
      // If using Svelte, do this instead:
      "shadcn-ui-svelte": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--framework",
          "svelte",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      },
      // If using Vue, do this instead:
      "shadcn-ui-vue": {
        "command": "npx",
        "args": [
          "@jpisnice/shadcn-ui-mcp-server",
          "--framework",
          "vue",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      }
    }
  }
}

Method 2: Using Claude Extension

Install Claude Extension:
- Search for "Claude" in VS Code extensions
- Install the official Claude extension
Configure MCP Server:
- Add to your VS Code settings.json:

{
  "claude.mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "vue"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Cursor Integration

Method 1: Global Configuration

Open Cursor Settings:
- Go to Settings (Cmd/Ctrl + ,)
- Search for "MCP" or "Model Context Protocol"
Add MCP Server Configuration:

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "svelte",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "vue",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

Method 2: Workspace Configuration

Create a .cursorrules file in your project root:

{
  "mcpServers": {
    "shadcn-ui": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "vue"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Code (Terminal) Integration

For Claude Code terminal users, you can add the MCP server directly:

# Add the shadcn-ui MCP server with GitHub token
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_API_KEY

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"
      ]
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "svelte",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // If using Vue, do this instead:
    "shadcn-ui-vue": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server",
        "--framework",
        "vue",
        "--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"
      }
    },
    // If using Svelte, do this instead:
    "shadcn-ui-svelte": {
      "command": "npx",
      "args": ["@jpisnice/shadcn-ui-mcp-server", "--framework", "svelte"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Continue.dev Integration

Install Continue.dev:
- Download from continue.dev
- Install the application
Configure MCP Server:
- Open Continue.dev
- Go to Settings → MCP Servers
- Add new server:

{
  "name": "shadcn-ui",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

For Svelte:

{
  "name": "shadcn-ui-svelte",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--framework",
    "svelte",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

Or for Vue:

{
  "name": "shadcn-ui-vue",
  "command": "npx",
  "args": [
    "@jpisnice/shadcn-ui-mcp-server",
    "--framework",
    "vue",
    "--github-api-key",
    "ghp_your_token_here"
  ]
}

🎯 Usage Examples

Getting Component Source Code

Ask your AI assistant:


"Show me the source code for the shadcn/ui button component"

The AI can now access the complete TypeScript source code for the button component.

Creating a Dashboard

Ask your AI assistant:


"Create a dashboard using shadcn/ui components. Use the dashboard-01 block as a starting point"

The AI can retrieve the complete dashboard block implementation and customize it for your needs.

Building a Login Form

Ask your AI assistant:


"Help me build a login form using shadcn/ui components. Show me the available form components"

The AI can list all available components and help you build the form.

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

🐛 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

Editor not recognizing MCP server:

# Verify the server is running
npx @jpisnice/shadcn-ui-mcp-server --help

# Check your editor's MCP configuration
# Ensure the command and args are correct

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 file for details.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📞 Support

🔗 Related Projects

shadcn/ui - React component library (default framework)
shadcn-svelte - Svelte component library
shadcn-vue - Vue component library
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!