One MCP server enables AI-assisted shadcn/ui component discovery and installation: the official shadcn MCP, built into the shadcn CLI (npx shadcn@latest mcp). This plugin's .mcp.json declares exactly that server.
Official shadcn MCP
Through this plugin
With the plugin enabled, Claude Code starts the server itself (npx shadcn@latest mcp). Its tools are named mcp__plugin_nextjs-provision_shadcn__<tool>. The server reads the project's components.json, so run the setup skill first in a project that has none.
In a user project (without the plugin)
pnpm dlx shadcn@latest mcp init --client claude
This generates the MCP configuration for Claude Code automatically. Supported --client values: claude, cursor, vscode, codex, opencode:
# Cursor
pnpm dlx shadcn@latest mcp init --client cursor
# VS Code
pnpm dlx shadcn@latest mcp init --client vscode
# Codex
pnpm dlx shadcn@latest mcp init --client codex
# opencode
pnpm dlx shadcn@latest mcp init --client opencode
Or write the server into the project's .mcp.json yourself — see component-search/references/mcp-config-template.json:
{
"mcpServers": {
"shadcn": {
"command": "npx",
"args": ["shadcn@latest", "mcp"]
}
}
}
Tools
The server exposes seven tools (shadcn 4.21.1):
| Tool | Description |
|---|---|
get_project_registries |
List the registries configured in components.json (requires that file — init creates it) |
list_items_in_registries |
Page through items of the given registries; filter with types (ui, block, component, hook, page, theme, style, base, font, ...), limit, offset |
search_items_in_registries |
Fuzzy search by name/description across the given or all configured registries |
view_items_in_registries |
Item details and file contents; items are written @registry/item |
get_item_examples_from_registries |
Usage examples and demos with full code (accordion-demo, example-booking-form, ...) |
get_add_command_for_items |
The npx shadcn@latest add ... command for a list of @registry/item addresses |
get_audit_checklist |
Checklist to run after adding components or generating code |
Registry and component search work across every registry configured in components.json, including shadcn studio (@ss-*) and any community registry you added.
Known quirks (shadcn 4.21.1)
search_items_in_registriesprintsAdd command: [object Promise]for every hit. Do not copy it — build the command (npx shadcn@latest add @registry/item) or callget_add_command_for_items.- A registry that is not listed in
components.jsonreturnsNOT_CONFIGUREDfrom the MCP tools (for example@magicuiin a project with"registries": {}), although the CLI itself resolves@registry/itemfor any directory entry. Configure it first with/add-registriesornpx shadcn registry add.
The community server is no longer shipped
Earlier versions of this plugin also declared @jpisnice/shadcn-ui-mcp-server. It was removed in 1.3.0: its get_component returns the Radix variant (asChild, Slot) even with --ui-library base, get_component_metadata answers "Component metadata not found" for common components such as button and accordion, and its list_components lists outdated form / sonner entries. Use the official tools above, or the CLI:
| Need | Use |
|---|---|
| Component source for your project's base | npx shadcn@latest view @shadcn/button or view_items_in_registries |
| Usage docs, API and examples | npx shadcn@latest docs button |
| Demo code | get_item_examples_from_registries |
| Themes and presets | npx shadcn@latest apply <preset>, https://ui.shadcn.com/create (see theme-configuration) |
Workflow: AI-Assisted Component Installation
1. User describes UI need ("I need a login form")
↓
2. AI uses search_items_in_registries / list_items_in_registries to find components and blocks
↓
3. AI uses view_items_in_registries / get_item_examples_from_registries to review options and dependencies
↓
4. AI gets the command from get_add_command_for_items (npx shadcn@latest add ...)
↓
5. User runs the command (or AI runs it via Bash, `--dry-run` first)
↓
6. AI customizes the installed component, then runs get_audit_checklist
Multi-Registry Search with MCP
The official MCP only searches registries listed in components.json. To search the community directory:
- Add registries to
components.json(/add-registriesfetches the directory, skipsunavailableand hidden entries, and merges the rest; see thecomponent-searchskill) - Or add a handful with
npx shadcn registry add @name=https://domain.com/r/{name}.json
Registries can also be declared in package.json#registries (CLI 4.18+; merged with components.json).
Troubleshooting
| Issue | Fix |
|---|---|
| MCP server not connecting | Check /mcp or claude mcp list; the server is started with npx shadcn@latest mcp — run that command once by hand to see errors |
NOT_CONFIGURED for a registry |
Add the registry to components.json (see above) |
Empty get_project_registries |
No components.json or no registries in it yet — run npx shadcn@latest init, or add registries |
What This Skill Does NOT Cover
- General Next.js MCP devtools -- see
nextjs-devplugin'smcp-toolsskill - Component installation details -- see
component-registryskill - shadcn/ui initialization -- see
setupskill - Community registry search and catalog -- see
component-searchskill