Component Search

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 contains 267 registries (Aug 2026) — always up to date.

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. Registries additionally support server-side dynamic search (?q=&limit=&offset=), which powers shadcn search.

But the official shadcn MCP server only searches registries listed in components.json. To enable MCP-assisted search across all registries, 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 website
• description — Brief description

Always fetch this endpoint instead of using a hardcoded list — it's maintained by the shadcn team and always current.

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 all registries
     ↓
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 all 260+ registries from the official endpoint and add them 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:

1. Fetch the registry list:

   curl -s https://ui.shadcn.com/r/registries.json
   

2. For each entry, add to components.json "registries" field using the name as key and url as value:

   {
     "registries": {
       "@magicui": "https://magicui.design/r/{name}.json",
       "@aceternity": "https://ui.aceternity.com/r/{name}.json"
     }
   }
   

3. 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

Two MCP servers are configured in this plugin's .mcp.json:

Dual search strategy

1. Official MCP searches all configured registries — add community registries to components.json to expand its scope
2. Jpisnice MCP searches the shadcn/ui GitHub repository for component source, demos, and blocks — useful for understanding how components work before installing

For projects that want both MCPs, copy the template from references/mcp-config-template.json to the project's .mcp.json.

Jpisnice MCP rate limits

Without a GitHub token: 60 requests/hour. With a token: 5000/hour.

To add a token:

claude mcp add shadcn-community -- npx -y @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_YOUR_TOKEN

Or set GITHUB_PERSONAL_ACCESS_TOKEN in the MCP server's env config. Create a fine-grained token with no special permissions (public repo access only).

Registry Categories

See references/community-registries.md for the full list with URLs and descriptions.

Full directory (267 registries): 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-registry skill
• Initial shadcn/ui project setup — see setup skill
• MCP server configuration details — see mcp-tools skill
• Theme customization — see theme-configuration skill