How Community Registries Work
shadcn v4 supports custom registries via the "registries" field in components.json. Any registry that implements the shadcn registry protocol can be added. The official registry directory at https://ui.shadcn.com/r/registries.json held 418 registries on 2026-10-02 (380 not hidden; 326 healthy, 41 degraded, 39 unavailable, 12 observing) — always fetch it instead of trusting a number.
The CLI can install from any registry without configuration:
npx shadcn@latest add @magicui/shimmer-button
The CLI also installs straight from public GitHub repos — no build step, just a registry.json at the repo root:
npx shadcn@latest add <user>/<repo>/<item>
GitHub registries work with list, search, view, and add, and — since CLI 4.19 — also with private repositories: if the repo is not publicly readable the CLI reads it through gh (gh auth login, nothing else to configure), or through GH_TOKEN / GITHUB_TOKEN where gh is not installed (use a fine-grained token with read-only Contents access). Public repos are always tried anonymously first. Registries additionally support server-side dynamic search (GET /r/registry.json?q=&limit=&offset=), which powers shadcn search.
Registries can be declared in components.json or, since CLI 4.18, in package.json#registries (the two are merged).
The official shadcn MCP server only searches registries listed in the project's components.json. To enable MCP-assisted search across the directory, populate them from the official endpoint.
Dynamic Registry Source
The authoritative list of all shadcn-compatible registries:
https://ui.shadcn.com/r/registries.json
Returns a JSON array. Each entry has:
name— Registry identifier (e.g.,"@magicui")url— Registry endpoint with{name}placeholder (e.g.,"https://magicui.design/r/{name}.json")homepage— Project websitedescription— Brief descriptionhealth—status(healthy|degraded|unavailable|observing),hidden,score,statusReason, availability figuresranking—scoreanditemCount(missing for registries that are not ranked yet)
Always fetch this endpoint instead of using a hardcoded list — it's maintained by the shadcn team and always current.
Filter by health before recommending or bulk-adding. Skip health.status == "unavailable" and health.hidden == true (39 entries on 2026-10-02: all unavailable, 38 of them hidden — they would not install). Say so when you recommend a degraded registry (e.g. sampled items failing validation); prefer healthy ones with a high ranking.score:
curl -s https://ui.shadcn.com/r/registries.json | python3 -c '
import json, sys
for r in json.load(sys.stdin):
h = r.get("health", {})
if h.get("status") in ("healthy", "observing") and not h.get("hidden"):
print(r["name"], r["url"])'
Search Workflow
1. User describes what they need ("animated button", "pricing section", "chat component")
↓
2. Fetch https://ui.shadcn.com/r/registries.json — scan descriptions for matches
↓
3. Consult references/community-registries.md for category-based recommendations
↓
4. Check user's components.json — are registries configured?
If not → run /add-registries to populate the available registries
(the CLI can already install @registry/item for any directory entry
without it — the bulk step only matters for MCP search)
↓
5. Use MCP tools to search, or install directly via CLI
↓
6. Install: npx shadcn@latest add @[registry]/[component]
↓
7. Verify the component renders correctly
Adding Registries to components.json
Add all registries (recommended)
Use the /add-registries command to fetch the registries from the official endpoint, skip the unavailable and hidden ones, and add the rest to components.json automatically.
Add a handful natively
The CLI's native method (supersedes hand-editing):
npx shadcn registry add @magicui=https://magicui.design/r/{name} @coss=https://coss.com/ui/r/{name}.json
Registry authors can check their registry with npx shadcn registry validate.
Or manually:
Fetch the registry list:
curl -s https://ui.shadcn.com/r/registries.jsonFor each entry, add to
components.json"registries"field using thenameas key andurlas value:{ "registries": { "@magicui": "https://magicui.design/r/{name}.json", "@aceternity": "https://ui.aceternity.com/registry/{name}.json" } }Merge with existing registries — do not overwrite the
"registries"object, add to it.
Add a single registry
{
"registries": {
"@registryname": "https://domain.com/r/{name}.json"
}
}
Installing from a Community Registry
# Install a single component
npx shadcn@latest add @magicui/shimmer-button
# Install multiple components from the same registry
npx shadcn@latest add @magicui/shimmer-button @magicui/animated-beam @magicui/globe
# Install from different registries in one command
npx shadcn@latest add @magicui/shimmer-button @aceternity/moving-border
# Force overwrite existing files
npx shadcn@latest add @magicui/shimmer-button --overwrite
The CLI auto-resolves registry URLs. Even without components.json configuration, the CLI can install from any known registry by name.
MCP-Assisted Search
This plugin's .mcp.json declares one MCP server: the official shadcn server (npx shadcn@latest mcp). It searches the registries listed in the project's components.json — add community registries there to expand its scope. Through this plugin its tools are named mcp__plugin_nextjs-provision_shadcn__<tool>:
| Tool | Use |
|---|---|
get_project_registries |
Which registries components.json configures |
search_items_in_registries |
Fuzzy search across (selected) registries |
list_items_in_registries |
Page through a registry's items (types, limit, offset) |
view_items_in_registries |
Item details and file contents — @registry/item |
get_item_examples_from_registries |
Demos and usage code (calendar-demo, example-hero, ...) |
get_add_command_for_items |
The npx shadcn@latest add ... command for given @registry/item addresses |
get_audit_checklist |
Post-install checklist after adding components |
Known quirks (shadcn 4.21.1): search_items_in_registries prints Add command: [object Promise] — build the command yourself (npx shadcn@latest add @registry/item) or call get_add_command_for_items. A registry that is not in components.json (for example @magicui in a fresh project) returns NOT_CONFIGURED from the MCP even though the CLI installs from it — configure it first (/add-registries or npx shadcn registry add).
The community MCP server @jpisnice/shadcn-ui-mcp-server is no longer shipped with this plugin: its get_component returns the Radix variant even with --ui-library base, and get_component_metadata answers "not found" for common components. For component source and demos use npx shadcn@latest view @registry/item, npx shadcn@latest docs <component>, or the tools above.
Without the MCP, the CLI covers the same ground: npx shadcn@latest search @registry -q "<term>", npx shadcn@latest view @registry/item, npx shadcn@latest add @registry/item --dry-run.
To use the server in a user project (not through this plugin), run npx shadcn@latest mcp init --client claude — see the mcp-tools skill, and references/mcp-config-template.json for a ready .mcp.json.
Registry Categories
| Category | Registries | Component Types |
|---|---|---|
| Animation & Motion | @magicui, @aceternity (degraded), @animate-ui, @cult-ui, @motion-primitives | Animated buttons, scroll effects, parallax, globe, beams |
| Extended UI | @coss (ex-Origin UI), @diceui, @basecn, @8bitcn, @boldkit, @8starlabs-ui, @cardcn | Extra components, retro/pixel style, card variants, dice rolls |
| Blocks & Sections | @bundui, @blocks-so, @efferd (degraded) | Landing page sections, marketing blocks, dashboards |
| E-Commerce | @commercn | Product cards, cart, checkout, reviews |
| AI Components | @ai-elements, @assistant-ui, @tool-ui | Chat bubbles, prompt inputs, AI response streams, LLM UIs |
| File Upload | @better-upload | Upload components, drag-and-drop, progress indicators |
| Editors & misc | @plate, @shadcn-editor, @kibo-ui, @kokonutui, @reui, @intentui, @tailark (degraded), @retroui, @smoothui, @skiper-ui, @paceui (degraded), @clerk, @supabase | Rich text editors, design-system kits, auth/backend UIs |
| Other | @arc, @abui (degraded), @aevr, @unlumen-ui (degraded), @einui, @billingsdk | Specialized UI, billing forms, misc |
Also degraded on 2026-10-02: @shadcnblocks. unavailable (do not recommend): @chamaac, @doras-ui, @creative-tim, @ai-blocks, @hextaui, @neobrutalism. Re-check health in the live directory before relying on this table.
See references/community-registries.md for the full list with URLs and descriptions.
Full directory (418 registries on 2026-10-02): https://ui.shadcn.com/docs/directory
CLAUDE.md Section for User Projects
When setting up a project with community registries, add the section from references/claude-md-section.md to the project's CLAUDE.md. This ensures Claude always searches registries before building components from scratch.
Verifying a Registry Works
Test that a registry URL is correct by installing a known component:
# Install a component from the registry
npx shadcn@latest add @magicui/shimmer-button
# If the install succeeds, the registry URL is correct
# If it fails, check the registry's documentation for the correct URL pattern
The standard URL convention is https://domain.com/r/{name} but some registries may differ. The CLI auto-resolves known registry names — if @registryname/component works, the URL is valid.
What This Skill Does NOT Cover
- Standard shadcn/ui and shadcn studio components — see
component-registryskill - Initial shadcn/ui project setup — see
setupskill - MCP server configuration details — see
mcp-toolsskill - Theme customization — see
theme-configurationskill