A powerful MCP (Model Context Protocol) server that provides AI assistants with comprehensive tools to work with shadcn/ui v4 components. This server acts as a bridge between AI assistants and the shadcn/ui ecosystem, offering source code access, demos, blocks support, and CLI integration.
# Use directly with npx (no installation needed)
npx @sherifbutt/shadcn-ui-mcp-server
# Or install globally for faster startup
npm install -g @sherifbutt/shadcn-ui-mcp-server
shadcn-ui-mcp-server
#
Then configure it in Claude Desktop (see detailed setup below).
Once configured, try these example interactions:
node --version
)No installation required! Use directly with npx:
# First time usage - downloads and runs automatically
npx @sherifbutt/shadcn-ui-mcp-server
# Subsequent uses - uses cached version unless updated
npx @sherifbutt/shadcn-ui-mcp-server@latest
Pros: Always gets the latest version, no disk space used Cons: Slightly slower startup on first run
# Install once, use anywhere
npm install -g @sherifbutt/shadcn-ui-mcp-server
# Run from anywhere
shadcn-ui-mcp-server
Pros: Fastest startup time Cons: Takes disk space, manual updates needed
# Install in your project
npm install @sherifbutt/shadcn-ui-mcp-server
# Run from project directory
npx @sherifbutt/shadcn-ui-mcp-server
Pros: Version pinned to project Cons: Separate installation per project
# Clone and build from source
git clone https://github.com/sherifButt/shadcn-ui-mcp-server.git
cd shadcn-ui-mcp-server
# Install dependencies
npm install
# Build the TypeScript code
npm run build
# Run locally
npm start
Use case: Contributing to the project or customization
Choose your installation method:
# Option 1: Use directly with npx (no installation needed)
npx @sherifbutt/shadcn-ui-mcp-server
# Option 2: Install globally for faster startup
npm install -g @sherifbutt/shadcn-ui-mcp-server
Configure Claude Desktop:
Test the connection:
## Front End Roles
When a task requires building or modifying a user interface, you must use the tools available in the shadcn-ui MCP server.
### Planning Rule
When planning a UI build using shadcn :
1. Discover Assets: First, use `list_components()` and `list_blocks()` to see all available assets in the MCP server.
2. Map Request to Assets: Analyse the user's request and map the required UI elements to the available components and blocks.
3. Prioritise Blocks: You should prioritise using blocks ( `get_block` ) wherever possible for common, complex UI patterns (e.g., login pages, calendars, dashboards). Blocks provide more structure and accelerate development. Use individual components ( `get_component` ) for smaller, more specific needs.
### Implementation Rule
When implementing the UI:
1. Get a Demo First: Before using a component, you must call the `get_component_demo(component_name)` tool. This is critical for understanding how the
component is used, its required props, and its structure.
2. Retrieve the Code:
- For a single component, call get_component(component_name) .
- For a composite block, call get_block(block_name) .
3. Implement Correctly: Integrate the retrieved code into the application, customising it with the necessary props and logic to fulfil the user's request.
Please act as a Lead UX Architect. Your task is to create a detailed UX Structure Plan for the above web application. The final output must be a single Markdown (UX_Structure_Planpo.md) file. The structure of this file is critical: it must use a hierarchical, indented list with box-drawing characters (like āāā and āāā) to create a clear tree structure, exactly like the provided reference style.
Please look at the @UX_Structure_Plan.md and make an ui-implementation using shaden ui as to what components will be used in the ui structure and where. And you should only write the name of the appropriate components to be used. Not the code.
Please act as a Lead Backend Architect. Your task is to create a detailed Backend Structure Plan for the above web application. The final output must be a single Markdown (.md) file. The structure of this file is critical: it must use a hierarchical, indented list with box-drawing characters (like āāā and āāā) to create a clear tree structure, exactly like the provided reference style.
Try these commands to get started:
"Show me all available shadcn/ui components"
"Get the source code for the Button component"
"Install form components for a login page"
"Show me dashboard blocks"
"Get demo code for the Card component"
Initialize shadcn/ui in your project:
"Initialize shadcn/ui in my project at /path/to/project"
Install components:
"Install button, input, and form components"
Get implementation help:
"Show me how to create a login form with validation"
"Get demo code for a data table"
Locate your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.config/Claude/claude_desktop_config.json
Add the shadcn-ui MCP server to your configuration:
Option A: Using npx (recommended)
{
"mcpServers": {
"shadcn-ui": {
"command": "npx",
"args": ["@sherifbutt/shadcn-ui-mcp-server"]
}
}
}
Option B: If installed globally
{
"mcpServers": {
"shadcn-ui": {
"command": "shadcn-ui-mcp-server"
}
}
}
Option C: Development setup
{
"mcpServers": {
"shadcn-ui": {
"command": "node",
"args": ["/absolute/path/to/shadcn-ui-mcp-server/dist/index.js"]
}
}
}
Claude code CLI:
# Add the MCP server
claude mcp add shadcn-ui npx @sherifbutt/shadcn-ui-mcp-server
# List configured MCP servers
claude mcp list
# Remove an MCP server (if needed)
claude mcp remove shadcn-ui
Restart Claude Desktop for the changes to take effect.
Verify the connection: Look for the š icon in Claude Desktop indicating MCP servers are connected.
For other MCP-compatible clients, use the same command configurations:
npx
or shadcn-ui-mcp-server
["shadcn-ui-mcp-server"]
(for npx)Server not connecting?
node --version
npx @sherifbutt/shadcn-ui-mcp-server
(should run without errors)Installation issues?
npm cache clean --force
npm install -g @sherifbutt/shadcn-ui-mcp-server
npm run build
Permission errors?
chmod +x dist/index.js
node dist/index.js
The server provides the following tools:
list_components
- List all components with optional category filtering
{
"category": "form" // optional: form, layout, navigation, overlay, feedback, etc.
}
get_component_source
- Get the TypeScript source code for a component
{
"name": "button" // required: component name
}
get_component_metadata
- Get component dependencies and configuration
{
"name": "dialog" // required: component name
}
get_component_demo
- Get usage examples and demo code
{
"name": "card",
"demoIndex": 0 // optional: which demo to retrieve
}
install_component
- Install components using the CLI
{
"components": ["button", "card", "dialog"],
"force": false, // optional: overwrite existing files
"cwd": "/path/to/project" // optional: working directory
}
list_blocks
- List available blocks with optional category filtering
{
"category": "dashboard" // optional: authentication, dashboard, layout, charts, forms
}
get_block_source
- Get complete block implementation
{
"name": "dashboard-01" // required: block name
}
install_block
- Install a block with all dependencies
{
"name": "authentication-01",
"force": false,
"cwd": "/path/to/project"
}
browse_repository
- Explore repository structure
{
"path": "apps/www/components/ui" // optional: repository path
}
search_repository
- Search for files and content
{
"query": "button",
"fileType": "tsx" // optional: filter by file extension
}
init_shadcn
- Initialize shadcn/ui in a project
{
"style": "default", // optional: default or new-york
"typescript": true,
"tailwindConfig": "./tailwind.config.js",
"componentsPath": "./components",
"force": false,
"cwd": "/path/to/project"
}
check_project_status
- Check project configuration
{
"cwd": "/path/to/project" // optional: working directory
}
The server includes metadata and demos for all shadcn/ui components:
The server provides access to complete block implementations:
Here are some example interactions with the server:
// Request
{
"tool": "get_component_source",
"arguments": { "name": "button" }
}
// Response includes full TypeScript source code
// Request
{
"tool": "install_component",
"arguments": {
"components": ["form", "input", "label", "button"],
"cwd": "/my-project"
}
}
// Executes: npx shadcn-ui@latest add form input label button
// Request
{
"tool": "get_block_source",
"arguments": { "name": "dashboard-01" }
}
// Response includes all files and dependencies for the dashboard
# Install dependencies
npm install
# Build the project
npm run build
# Watch mode for development
npm run dev
# Run type checking
npm run lint
# Clean build directory
npm run clean
The server is built with:
@modelcontextprotocol/sdk
for MCP protocol implementationsrc/
āāā index.ts # Main MCP server implementation
āāā types/ # TypeScript type definitions
āāā data/ # Component and block registries
āāā services/ # External service integrations
ā āāā registry.ts # shadcn/ui registry API client
ā āāā cli.ts # CLI command execution
āāā utils/ # Utility functions
āāā demos.ts # Demo code generation
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details
A: Look for the š icon in Claude Desktop indicating MCP servers are connected. You can also ask "List all shadcn/ui components" to test.
A: Yes! The server works with any project. Use the init_shadcn
and install_component
tools to set up shadcn/ui in your project.
A: No! Using npx @sherifbutt/shadcn-ui-mcp-server
requires no global installation.
A: Components are individual UI elements (button, input, etc.). Blocks are complete implementations (login pages, dashboards, etc.).
A: The server fetches live data from the official shadcn/ui registry, so you always get the latest versions.
A: Yes! The server supports both TypeScript and JavaScript projects. Components are provided in TypeScript but work in both.