05eb2b968b
- Search across multiple registries and make the registry argument optional: omit it to search every registry configured in components.json (builtins like @shadcn excluded). Without a components.json or configured registries, a clear usage error is printed. - Add a --type filter (accepts "ui" or "registry:ui", comma-separated) with validation against the known item types. - Fetch registries concurrently with a capped worker pool, preserving result order. - Tolerate per-registry failures when searching all configured registries (reported in a structured `errors` field); exit non-zero when every registry fails. Usage errors print directly instead of routing through handleError. - MCP parity: optional registries (search-all), a `types` filter, and type validation across the search/list/examples tools. - Keep the public registry surface to `searchRegistries` and make it self-contained (clears its own context, useCache defaults to false). - Consolidate search formatting into registry/search, add the `errors` field to searchResultsSchema, and update the skill docs.
3.4 KiB
shadcn MCP Server
The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
Setup
shadcn mcp # start the MCP server (stdio)
shadcn mcp init # write config for your editor
Editor config files:
| Editor | Config file |
|---|---|
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
| VS Code | .vscode/mcp.json |
| OpenCode | opencode.json |
| Codex | ~/.codex/config.toml (manual) |
Tools
Tip: MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use
npx shadcn@latest info— there is no MCP equivalent.
shadcn:get_project_registries
Returns registry names from components.json. Errors if no components.json exists.
Input: none
shadcn:list_items_in_registries
Lists all items from one or more registries. Registries can be configured
namespaces such as @acme, public GitHub sources such as owner/repo, or
registry catalog URLs. Omit registries to list from every registry configured
in components.json.
Input: registries (string[], optional — omit for all configured), types (string[], optional — e.g. ["ui", "block"]), limit (number, optional, defaults to 100), offset (number, optional)
shadcn:search_items_in_registries
Fuzzy search across registries. Registries can be configured namespaces, public
GitHub sources, or registry catalog URLs. Omit registries to search every
registry configured in components.json — e.g. "find me a hero" across all
configured registries.
Input: registries (string[], optional — omit for all configured), query (string), types (string[], optional — e.g. ["ui", "block"]), limit (number, optional, defaults to 100), offset (number, optional)
shadcn:view_items_in_registries
View item details including full file contents.
Input: items (string[]) — e.g.
["@shadcn/button", "@shadcn/card", "owner/repo/item"]
shadcn:get_item_examples_from_registries
Find usage examples and demos with source code. Omit registries to search
every registry configured in components.json.
Input: registries (string[], optional — omit for all configured), query (string) — e.g. "accordion-demo", "button example"
shadcn:get_add_command_for_items
Returns the CLI install command.
Input: items (string[]) — e.g. ["@shadcn/button"]
shadcn:get_audit_checklist
Returns a checklist for verifying components (imports, deps, lint, TypeScript).
Input: none
Configuring Registries
Namespaced and authenticated registries are set in components.json. The
@shadcn registry is always built-in. Public GitHub registries can also be used
directly as owner/repo registry sources when the repository has a root
registry.json; they do not need components.json configuration.
{
"registries": {
"@acme": "https://acme.com/r/{name}.json",
"@private": {
"url": "https://private.com/r/{name}.json",
"headers": { "Authorization": "Bearer ${MY_TOKEN}" }
}
}
}
- Names must start with
@. - URLs must contain
{name}. ${VAR}references are resolved from environment variables.
Community registry index: https://ui.shadcn.com/r/registries.json