What is the shadcn MCP server?
The shadcn MCP server is part of the shadcn CLI. You start it with npx shadcn@latest mcp over stdio, and your agent can then browse, search and view items from registries, and get the install command. Registries are set in components.json. The default shadcn/ui registry needs no configuration.
The shadcn MCP server lets AI assistants interact with items from component registries. You can browse what a registry offers, search for a component by name or purpose, view its source and install it into your project through natural-language prompts. For the skill side, see the shadcn skill.
It ships inside the shadcn CLI, so there is no separate package to track. The server runs locally over stdio when your agent launches npx shadcn@latest mcp.
What it changes in your workflow
- Your agent finds a component in a registry before it writes custom UI, then gets the exact install command.
- It can view full file contents and usage examples, so generated code matches the registry's own source.
- It works with the default shadcn/ui registry, third-party registries, private company registries and namespaced ones such as @acme.
- It handles registry operations only. For aliases, framework and Tailwind version, the repo's guide points you to the CLI info command.
Hosted or local
| shadcn MCP server | |
|---|---|
| Where it runs | On your machine, started by the CLI |
| Transport | stdio |
| Account or key | None for the default registry. Private registries use tokens set through environment variables |
| Config needed | A components.json for custom registries and for the project-registry tool |
Who it is for
Best for
- Projects built on shadcn/ui that want an agent to add components from the right registry.
- Teams with an internal registry who want agents to use it instead of reinventing components.
- Developers who want a searchable catalog inside the agent instead of switching to the docs site.
Not for
- Rules about how to compose components. That guidance lives in the shadcn skill, which the shadcn docs present as a companion.
- Reading project configuration. There is no MCP tool for it, so use
npx shadcn@latest info. - Reading design files. The server only handles registries, so for Figma frames see Figma MCP.
Use it with UiChemy
The server installs React components into your own front end. For WordPress, UiChemy covers the other side: Composer is a visual editor for Elementor or Gutenberg, and AI to WordPress imports an existing AI build as an editable page. Click Get Started on uichemy.com. For polishing the components it installs, see the shadcn improve skill.
Connect shadcn MCP Server: Browse and Install Components to your AI client
npx shadcn@latest mcp init --client cursorRun the init command
In your project, run
npx shadcn@latest mcp init --client <client>. The CLI help in the docs shows claude, cursor, vscode, codex and opencode as clients. The docs show the pnpm form aspnpm dlx shadcn@latest mcp init --client claude.Or add the config by hand
Put the config above in your client's file: .mcp.json for Claude Code, .cursor/mcp.json for Cursor, and .vscode/mcp.json for VS Code, which uses a servers key instead of mcpServers.
Codex needs a manual edit
The docs say the CLI cannot update ~/.codex/config.toml for you. Add a [mcp_servers.shadcn] table with command npx and args shadcn@latest and mcp, then restart Codex.
Restart and check
Restart your client. In Claude Code, run /mcp and look for Connected. In Cursor, enable the server in settings and look for the green dot.
Try a prompt
Ask for all components in the shadcn registry, or ask it to add the button, dialog and card components to your project.
Client configuration
{
"mcpServers": {
"shadcn": {
"command": "npx",
"args": ["shadcn@latest", "mcp"]
}
}
}Endpoints and ports
npx shadcn@latest mcpStarts the server over stdio. Your client normally runs it for you.npx shadcn@latest mcp initWrites the config for your editor, except Codex, which is manual.components.jsonHolds the registries object, including namespaces and private URLs with headers..env.localThe docs keep tokens, such as REGISTRY_TOKEN, in environment variables.https://ui.shadcn.com/docs/mcpOfficial setup, tools and troubleshooting page.What you can do with it
- Runs from the CLIThe server is started by
npx shadcn@latest mcp, so it follows the CLI version you choose and needs no separate install. - One-command config
mcp init --clientwrites the config for supported editors and prints the next step. Codex is the exception and needs a manual edit. - Several registry typesWorks with the default shadcn/ui registry, third-party registries, private registries and namespaced registries. The tool guide also mentions public GitHub sources and catalog URLs.
- Search with pagingListing and search accept types, limit and offset, so large registries can be browsed in pages instead of one long result.
- Full file viewThe view tool returns the item's file contents, so the agent reads the real source before it installs.
- Install command lookupThe agent gets the exact CLI command from the server and does not guess the command or its flags.
- Post-install auditA checklist tool covers imports, dependencies, lint and TypeScript for the components just added.
- Private registry authRegistries in components.json can carry headers, with tokens kept in environment variables such as REGISTRY_TOKEN set in .env.local.
Tools it exposes
get_project_registries
Returns the registry names set in components.json. It errors if the project has no components.json.
list_items_in_registries
Lists items from one or more registries. Accepts registries, types, limit (default 100) and offset. Omitting registries lists from every configured one.
search_items_in_registries
Fuzzy search across registries by query, with optional registries, types, limit and offset.
view_items_in_registries
Shows item details including full file contents, for items such as @shadcn/button.
get_item_examples_from_registries
Finds usage examples and demos with source code, for queries such as accordion-demo.
get_add_command_for_items
Returns the CLI command that installs the given items.
get_audit_checklist
Returns a checklist for verifying added components, covering imports, dependencies, lint and TypeScript.
Frequently asked questions
What is the shadcn MCP server?
It is the MCP server built into the shadcn CLI. It lets an AI assistant browse, search, view and get install commands for items in shadcn-compatible registries, using the registries set in your project's components.json.
How do I set up the shadcn MCP server?
Run npx shadcn@latest mcp init --client followed by your client name, or add a server entry with command npx and args shadcn@latest and mcp to your client's MCP config file. Then restart the client. Codex needs a manual edit of its TOML config.
Which AI coding agents work with the shadcn MCP server?
The shadcn docs give setup steps for Claude Code, Cursor, VS Code with GitHub Copilot, Codex and OpenCode. Any other MCP client that can start a stdio command should work with the same npx entry, but the docs do not confirm that.
Do I need a components.json file?
Not for the default shadcn/ui registry, which the docs say needs no configuration. You need components.json for custom registries, and the get_project_registries tool errors without it. The docs also say installs fail without a valid components.json.
Can it use a private registry?
Yes. Add the registry to components.json with its URL and headers, and keep tokens in environment variables such as REGISTRY_TOKEN in .env.local. The docs link a separate authentication page for details.
What should I do if the tools do not show up?
The docs suggest running npx clear-npx-cache, re-enabling the server in your client, and checking logs. In Cursor, logs are under View, Output. In Claude Code, run /mcp to see whether the server is connected.
How does the MCP server relate to the shadcn skill?
The server does registry work as tools. The shadcn skill supplies the rules for how to write with the components, and its docs include MCP setup. Using both lets the agent find an item through the server and use it by the skill's rules.