The Model Context Protocol (MCP) Server Integration exposes the shadcn/ui component registry and CLI features as an AI-compatible server interface. It enables AI assistants such as Claude Code, Cursor, VS Code, Codex, and OpenCode to interact programmatically with the component ecosystem.
Through the MCP server, AI agents can:
This integration bridges the AI natural language domain and the code entity domain, enabling natural language prompts to translate into actionable CLI and registry operations.
Sources: packages/shadcn/src/commands/mcp.ts90-107 apps/v4/content/docs/(root)/mcp.mdx6-9
The MCP server functions as a middle layer accepting AI assistant requests, querying the project and registry metadata, then returning structured responses.
This architecture unifies multiple AI clients interacting through a common MCP server that in turn queries the shadcn registry and CLI infrastructure.
Sources: packages/shadcn/src/commands/mcp.ts22-86 packages/shadcn/src/mcp/index.ts26-171 packages/shadcn/src/mcp/utils.ts14-22
The MCP server is implemented with the Server class from the @modelcontextprotocol/sdk package.
| Property | Value | Description |
|---|---|---|
name | "shadcn" | MCP server identifier exposed to clients |
version | "1.0.0" | Server version string |
capabilities | resources, tools | Supported MCP protocol capabilities |
The server is initialized in packages/shadcn/src/mcp/index.ts 26-37 and connected via StdioServerTransport when the shadcn mcp command is executed packages/shadcn/src/commands/mcp.ts101-102
The MCP server exposes the following tools, each corresponding to a key CLI or registry function:
| Tool Name | Purpose | Implementation |
|---|---|---|
get_project_registries | Returns registries configured in components.json | packages/shadcn/src/mcp/index.ts43-47 |
list_items_in_registries | Lists component items from specified registries | packages/shadcn/src/mcp/index.ts49-78 |
search_items_in_registries | Performs fuzzy search across registry items | packages/shadcn/src/mcp/index.ts80-113 |
view_items_in_registries | Retrieves detailed info and file contents for items | packages/shadcn/src/mcp/index.ts116-128 |
get_item_examples_from_registries | Returns usage example code snippets (demos) | packages/shadcn/src/mcp/index.ts130-147 |
get_add_command_for_items | Provides the CLI command string to add components | packages/shadcn/src/mcp/index.ts150-162 |
get_audit_checklist | Returns a checklist to verify component setup | packages/shadcn/src/mcp/index.ts164-167 |
Sources: packages/shadcn/src/mcp/index.ts39-171
The CLI supports several clients by writing configuration files and installing shadcn dependencies automatically.
| Client | Label | Config Path | Reference |
|---|---|---|---|
claude | Claude Code | .mcp.json | packages/shadcn/src/commands/mcp.ts24-35 |
cursor | Cursor | .cursor/mcp.json | packages/shadcn/src/commands/mcp.ts37-48 |
vscode | VS Code | .vscode/mcp.json | packages/shadcn/src/commands/mcp.ts50-61 |
codex | Codex | .codex/config.toml | packages/shadcn/src/commands/mcp.ts63-70 |
opencode | OpenCode | opencode.json | packages/shadcn/src/commands/mcp.ts72-85 |
shadcn mcp initThe init subcommand configures MCP support for the chosen client.
Key implementation details:
deepmerge to combine existing MCP configs packages/shadcn/src/commands/mcp.ts14 packages/shadcn/src/commands/mcp.ts250updateDependencies or runs execa to install shadcn@latest packages/shadcn/src/commands/mcp.ts157-174~/.codex/config.toml); the CLI prints instructions instead packages/shadcn/src/commands/mcp.ts176-192Sources: packages/shadcn/src/commands/mcp.ts114-225 packages/shadcn/src/commands/mcp.ts229-253
The MCP server leverages the core registry search engine to find components.
resolveSearchRegistries determines which registries to query (configured in components.json minus built-ins) packages/shadcn/src/registry/search.ts23-34searchRegistries fetches registry indices concurrently, capped by SEARCH_CONCURRENCY = 8 packages/shadcn/src/registry/search.ts38-67fuzzysort to match queries against component names and descriptions packages/shadcn/src/registry/search.ts196-225formatSearchResultsWithPagination packages/shadcn/src/mcp/utils.ts24-80The get_item_examples_from_registries tool specifically looks for registry items matching patterns like {item-name}-demo or example-{item-name} packages/shadcn/src/mcp/index.ts145 It returns the full code content of these files wrapped in markdown blocks packages/shadcn/src/mcp/utils.ts139-168
Sources: packages/shadcn/src/registry/search.ts69-182 packages/shadcn/src/mcp/utils.ts139-168
loadEnvFiles is called to ensure private registry credentials (API keys/tokens) are available to the server packages/shadcn/src/commands/mcp.ts100continueOnError. Failed registries are reported via formatSkippedRegistries rather than crashing the session packages/shadcn/src/mcp/utils.ts101-115 packages/shadcn/src/registry/search.ts82findUnknownTypesMessage ensures AI agents receive helpful feedback if they request invalid registry types (e.g., requesting a "widget" instead of "registry:ui") packages/shadcn/src/mcp/utils.ts84-97Sources: packages/shadcn/src/mcp/utils.ts82-116 packages/shadcn/src/registry/search.ts115-127
Sources: packages/shadcn/src/registry/schema.ts21-26 packages/shadcn/src/mcp/utils.ts14-22 packages/shadcn/src/registry/search.ts23-34
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.