Provides tools for accessing shadcn/ui v4 component source code, demos, blocks, metadata, and CLI integration for installing and managing components in projects.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@shadcn/ui MCP Server List all shadcn/ui components"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Related MCP server: shadcn-ui MCP Server
Once configured, try these example interactions:
"List all shadcn/ui form components" - See all available form-related components
"Get the Button component source code" - Fetch the latest TypeScript implementation
"Show me how to create a card with form" - Get demo code with examples
"Install dialog and form components in my project" - Use CLI integration
"What dashboard blocks are available?" - Browse pre-built layouts
📦 Component Source Code Access - Fetch latest shadcn/ui v4 TypeScript source code
🎨 Component Demos - Generate usage examples and demo code for all components
🏗️ Blocks Support - Access complete block implementations (dashboards, forms, etc.)
📋 Metadata Access - Get dependencies, descriptions, and configuration details
🔍 Repository Browsing - Explore the shadcn/ui repository structure
⚡ CLI Integration - Install and manage components via shadcn/ui CLI
🔧 Project Management - Initialize and check project status
Node.js 18+ (check with node --version)
npm or yarn package manager
Claude Desktop or another MCP-compatible client
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@latestPros: 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-serverPros: 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-serverPros: 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 startUse case: Contributing to the project or customization
Node.js 18+ installed on your system
Claude Desktop or another MCP-compatible client
Basic familiarity with shadcn/ui components
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-serverConfigure Claude Desktop:
Open Claude Desktop
Go to Settings → MCP Servers (or locate the config file manually)
Add the server configuration (see detailed steps below)
Test the connection:
Restart Claude Desktop
Look for the 🔌 MCP connection indicator
Try asking: "List all shadcn/ui form components"
## 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:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.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-uiRestart 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:
Command: npx or shadcn-ui-mcp-server
Args: ["shadcn-ui-mcp-server"] (for npx)
Transport: stdio
Server not connecting?
Ensure Node.js 18+ is installed: node --version
Test the server manually: npx @sherifbutt/shadcn-ui-mcp-server (should run without errors)
Check Claude Desktop config file syntax with a JSON validator
Restart Claude Desktop after config changes
Installation issues?
Clear npm cache: npm cache clean --force
Try global installation: npm install -g @sherifbutt/shadcn-ui-mcp-server
For development, ensure build completed: npm run build
Permission errors?
On Unix systems, ensure executable permissions: chmod +x dist/index.js
Try running with explicit node: 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:
Button, Checkbox, Form, Input, Input OTP, Label, Radio Group, Select, Slider, Switch, Textarea, Toggle, Toggle Group
Accordion, Aspect Ratio, Card, Collapsible, Resizable, Scroll Area, Separator, Tabs
Breadcrumb, Command, Dropdown Menu, Menubar, Navigation Menu, Pagination
Alert Dialog, Context Menu, Dialog, Drawer, Hover Card, Popover, Sheet, Tooltip
Avatar, Calendar, Carousel, Chart, Data Table, Table
Alert, Badge, Progress, Skeleton, Sonner, Toast
The server provides access to complete block implementations:
Login forms, Sign-up forms, Social authentication
Analytics dashboards, Admin panels, Metrics displays
Sidebars with navigation, Responsive layouts
Bar charts, Line charts, Pie charts, Area charts
Settings forms, Profile forms, Complex forms with validation
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 cleanThe server is built with:
TypeScript for type safety
@modelcontextprotocol/sdk for MCP protocol implementation
Modular architecture with separate services for registry, CLI, and demos
Comprehensive error handling with proper MCP error codes
src/
├── 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 generationContributions 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.
Browse the shadcn/ui repository structure
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Repository path to browse (e.g., "apps/www/components") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is solely responsible for disclosing behavior. It only states the action 'browse,' without explaining whether it is read-only, what data it returns, or any side effects. This is insufficient for an agent to understand the tool's operational implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is appropriately short, though it could benefit from slightly more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should explain what browsing entails (e.g., whether it lists files or shows directory tree). It fails to provide this context, and with no annotations, the tool is under-specified for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'path,' so the description adds no additional meaning beyond what the schema already provides. The baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool browses the shadcn/ui repository structure, using a specific verb and resource. However, it does not distinguish itself from sibling tools like list_blocks or list_components, which could lead to confusion about when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, appropriate scenarios, or exclusions, which is critical given the range of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the current project status and shadcn/ui configuration
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory to check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not state whether the tool is read-only, requires authentication, has side effects, or returns specific output. Minimal information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Every word contributes meaning, and the structure is front-loaded with the key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema description, so the return value is unknown. No information on what constitutes 'status' or 'configuration', nor any behavior for missing cwd. Incomplete for a check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter 'cwd' described as 'Working directory to check'). The description adds context about what is checked but no additional semantic detail for the parameter itself. Baseline score due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks 'current project status and shadcn/ui configuration', using a specific verb and resource. It is distinct from sibling tools like browse_repository or get_component_source which target different tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or constraints, leaving the agent to infer usage from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete source code for a shadcn/ui block
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the block |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose any behavioral traits (e.g., whether it fetches remotely, caching behavior, error cases). Only states the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimally complete for a simple one-parameter tool, but lacks any indication of return format, side effects, or limitations. Could benefit from examples or output shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for 'name' parameter. Description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses clear verb 'Get' and specific resource 'complete source code for a shadcn/ui block', which distinguishes it from sibling tools like get_component_source and install_block.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_component_source). No prerequisites or when-not-to-use conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get demo code and usage examples for a specific component
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the component | |
| demoIndex | No | Index of the demo to retrieve (defaults to 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states it retrieves data (implying read-only) but does not disclose rate limits, side effects, or other behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It could be improved by front-loading the purpose more explicitly, but it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters and no output schema or annotations, the description is minimally adequate. It does not cover return format, error handling, or what happens when demoIndex is omitted or invalid. However, for a simple retrieval tool, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters described), so baseline is 3. The description does not add meaning beyond the schema; it repeats 'for a specific component' but does not elaborate on the demoIndex parameter's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and resource (demo code and usage examples for a specific component). It distinguishes from sibling tools like get_component_source or get_component_metadata by specifying demo code and examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_component_source or get_component_metadata). There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a specific component including dependencies and description
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the component |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that metadata includes dependencies and description, but does not state whether the operation is read-only, safe, or any side effects. Adequate but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words, front-loaded with key action and resource, no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-param tool with no output schema, description covers purpose and key content but does not detail full metadata structure or return format. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with one parameter 'name' described as 'The name of the component'. Description adds no extra meaning beyond schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'metadata for a specific component', and contents 'dependencies and description'. Distinguished from siblings like get_component_source and get_component_demo by focusing on metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings like get_block_source or get_component_source. No mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the source code for a specific shadcn/ui component
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the component |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read operation but does not disclose what happens if the component is not found, any required permissions, or whether the output is raw code or formatted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the tool's purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is functionally complete. However, it lacks usage guidance that would help an agent decide when to invoke this tool over siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'name'. The description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the source code') and the resource ('specific shadcn/ui component'). It effectively distinguishes from sibling tools like 'get_component_demo' and 'get_component_metadata' by specifying 'source code'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_component_demo' or 'get_component_metadata'. No context on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize shadcn/ui in a project
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Which style to use | |
| typescript | No | Use TypeScript | |
| tailwindConfig | No | Path to tailwind config | |
| componentsPath | No | Path to components directory | |
| force | No | Force init (skip checks) | |
| cwd | No | Working directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'Initialize shadcn/ui' without disclosing what files are created, whether it's destructive, or any side effects. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence is concise but lacks structure. Not verbose, but could front-load key details or use bullet points for better readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain what initialization involves, what the outcome is, or how it relates to other tools like install_component.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The tool description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Initialize' and resource 'shadcn/ui', distinguishing it from sibling tools like install_component or list_components which handle components rather than project setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites mentioned, and no exclusions. The agent has no context to decide if init is appropriate for their current state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install a shadcn/ui block with all its dependencies
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the block to install | |
| force | No | Force overwrite existing files | |
| cwd | No | Working directory for the command |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It mentions dependencies but lacks disclosure of side effects (e.g., project config changes, file overwrites, error behaviors). Minimal behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, front-loaded with key action. Could be slightly expanded without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and tool modifies project state. Description lacks information on return values, error conditions, or prerequisites (e.g., initialized project). Incomplete for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds no additional parameter meaning beyond stating 'dependencies'. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'install' and the resource 'shadcn/ui block', and specifies it includes dependencies. It naturally distinguishes from sibling tools like install_component and init_shadcn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like install_component. No prerequisites, exclusions, or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install one or more shadcn/ui components using the CLI
| Name | Required | Description | Default |
|---|---|---|---|
| components | Yes | Array of component names to install | |
| force | No | Force overwrite existing files | |
| cwd | No | Working directory for the command |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry full burden. It only says 'install' without disclosing side effects like overwriting, project structure changes, or requirements. The force parameter hints at overwriting but the description does not elaborate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence. While not wasteful, it could be more informative without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description is too minimal. It omits success/error outcomes, required environment, and dependencies like having a project initialized with shadcn/ui. Siblings include init_shadcn, indicating a prerequisite not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds no extra meaning beyond the schema. For example, it does not define what constitutes a component name or explain the force behavior in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (install), the resource (shadcn/ui components), and the method (using the CLI). It distinguishes well from siblings like install_block or get_component_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as init_shadcn or install_block. Prerequisites like project initialization are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available shadcn/ui blocks with optional category filtering
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category (authentication, dashboard, layout, charts, forms, ecommerce, marketing, application) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says it lists blocks with filtering, but does not mention any side effects, read-only nature, or rate limits. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff. All words are meaningful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description is adequate. Could enhance by defining 'blocks' vs 'components', but given low complexity, it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the category parameter is fully described with enum and description). The description adds 'optional category filtering' but that is already implied by the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'shadcn/ui blocks', and adds 'with optional category filtering', which clearly distinguishes it from sibling tools like list_components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_components or search_repository. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available shadcn/ui components with optional category filtering
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category (form, layout, navigation, overlay, feedback, data-display, disclosure, data-entry, typography) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states that the tool lists components and can filter by category. It does not mention whether the tool is read-only, the size of the return set, or any other behavioral details like rate limits or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It is front-loaded and efficiently communicates the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description provides enough context for an AI agent to understand the tool's purpose. However, it could briefly mention that it returns a list of component names or objects, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter (category) with a full description and enum. The description does not add additional meaning beyond what the schema provides, so the score is at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing all available shadcn/ui components with optional category filtering. It uses a specific verb ('List') and resource ('shadcn/ui components'), which distinguishes it from sibling tools like get_component_demo or install_component.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing components before installing or getting details), but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Sibling tools like get_component_demo are distinct, but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files or content in the shadcn/ui repository
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| fileType | No | Filter by file type (e.g., "tsx", "ts", "css") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic function. It fails to mention what is searched (e.g., filenames, content, metadata), whether pagination exists, rate limits, or authentication needs. The minimal text does not adequately inform the agent of call side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's function. It earns its place with no wasted words, but it is perhaps too terse for a tool with many siblings, slightly reducing completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, no output schema, and multiple siblings (e.g., browse_repository, list_components), the description is insufficient. It does not clarify whether the search covers full text or just filenames, what the response format is, or how it relates to other tools for obtaining repository information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both query and fileType. The description adds nothing beyond what the schema already provides; it merely reiterates the search purpose. Baseline 3 is appropriate as the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for files or content in a specific repository. It identifies the verb ('Search'), resource ('files or content'), and scope ('shadcn/ui repository'), distinguishing it from siblings like browse_repository or get_component_source which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings (e.g., browse_repository for navigation, get_component_source for specific files). The description does not specify prerequisites or alternatives, leaving the agent to infer appropriate use from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation on specific entities: blocks vs components vs repository vs project init/status. No two tools have overlapping purposes, and descriptions clearly differentiate them.
All tool names follow a consistent snake_case verb_noun pattern (e.g., get_block_source, install_component, list_blocks). No mixing of conventions.
12 tools is well within the ideal range (3-15) for a focused server. Each tool serves a clear purpose without redundancy or bloat.
Covers init, listing, retrieval of source/demo/metadata, installation, and repository browsing/search. Minor gap: block metadata is missing (only component has metadata getter), but core workflows are fully supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
Versioned documentation registry and semantic search for AI tools and coding assistants.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sherifButt/shadcn-ui-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
