shadcn/ui MCP Server

The shadcn MCP server is the stdio server built into the shadcn CLI (npx shadcn@latest mcp). It gives Claude Code, Codex and Cursor seven tools to search, view and get install commands for components in the shadcn registry and in any private registry named in components.json. The server only reads; the shadcn add command still writes the files.

You ask the agent for a confirm-delete dialog. It writes 80 lines of hand-rolled modal with its own focus trap, while components/ui/alert-dialog.tsx is one shadcn add away, or already sits in the repo. With the registry in reach, the agent looks up what exists, installs the real component and composes it, so your UI stays on one design system.

This page is for developers who build React UIs with shadcn/ui and an agent, and for tech leads who own components.json and the company registry.

What you’ll walk away with from the shadcn MCP server

• The server installed in Claude Code, Codex and Cursor with shadcn mcp init, plus the manual Codex entry the CLI does not write for you.
• A decision on MCP server, shadcn skill, or both.
• Three copy-paste prompts: find and install components, build a feature from them, and pull from a private registry.
• A verification gate (dry run, type check, lint, tests and a screenshot) that proves the result without anyone reading the generated components.
• The traps that older guides and model memory repeat, checked against shadcn 4.21.0.

Should you use the MCP server, the shadcn skill, or both?

shadcn ships two agent integrations, and they overlap more than their names suggest. The shadcn skill (from the shadcn-ui/ui repository) teaches the agent to drive the CLI itself: it starts with npx shadcn@latest info --json, reads component docs with npx shadcn@latest docs <component> and checks for existing components before writing custom UI. The MCP server exposes the registry as structured tools the agent calls directly.

Need	Reach for	Why
Add, fix and style components in one project	the skill	It costs about 100 tokens of description until it fires, and it reads your project config first
Search across several namespaced registries (@shadcn, @acme)	the MCP server	Fuzzy search and item views across every registry in components.json
A team rollout where every client should behave the same	both	The skill supplies the working method; the server supplies registry search
Migrate a project from Radix UI to Base UI	the migrate-radix-to-base skill	It ships in the same repository and migrates a single component or a whole project

Install the skill with the skills CLI (listing checked in September 2026 with skills 1.7.0; the repository holds shadcn and migrate-radix-to-base):

# Terminal, project root. --skill limits the install to the one skill you want.
npx skills add shadcn/ui --skill shadcn

The shadcn/improve skill is a different thing with a similar name: a codebase audit-and-plan workflow, covered on its own page. For installing, updating and scoping skills in general, see installing and managing skills.

Install the shadcn MCP server in Claude Code, Codex and Cursor

The server entry is identical in every client: npx shadcn@latest mcp. What differs is who writes the config file. The CLI’s mcp init --client accepts claude, cursor, vscode, codex and opencode (checked against shadcn mcp init --help, 4.21.0).

1. Initialise shadcn/ui in the project if it has no components.json yet. The registry tools read their registry list from that file.

   npx shadcn@latest init

2. Register the server for your client.

   Claude Code

   # Writes the "shadcn" entry to .mcp.json in the project root
   npx shadcn@latest mcp init --client claude

   Or register it with Claude Code’s own command, shared with the team through .mcp.json:

   claude mcp add --scope project shadcn -- npx shadcn@latest mcp

   Run /mcp in a session to confirm the server is connected and approve the project server when asked.

   Codex

   mcp init --client codex does not edit your Codex config; it prints the block to add and stops. Add it yourself to ~/.codex/config.toml:

   [mcp_servers.shadcn]
   command = "npx"
   args = ["shadcn@latest", "mcp"]

   Or let Codex write the same entry:

   codex mcp add shadcn -- npx shadcn@latest mcp
   codex mcp list   # shadcn should appear

   Restart Codex so it loads the server.

   Cursor

   # Writes the "shadcn" entry to .cursor/mcp.json in the project root
   npx shadcn@latest mcp init --client cursor

   The resulting file:

   {
     "mcpServers": {
       "shadcn": {
         "command": "npx",
         "args": ["shadcn@latest", "mcp"]
       }
     }
   }

   Enable the server in Cursor’s MCP settings if it shows as disabled.

3. Check the side effect. In a September 2026 test with shadcn 4.21.0, mcp init also added shadcn to devDependencies and created a lockfile when none existed. Commit that change deliberately or revert it.

The @latest tag resolves on every server start. To keep a team on one version, pin it in the args ("shadcn@4.21.0") and bump it in a normal pull request.

What the seven shadcn MCP tools do

The tool list below was read from the server’s tools/list response (shadcn 4.21.0, September 2026). Older guides list six and miss get_project_registries.

Tool	What it returns
get_project_registries	The registry names configured in components.json; an empty list (no error) when the file is missing, despite its description
list_items_in_registries	Items in one or more registries, filterable by type
search_items_in_registries	Fuzzy search over item names and descriptions
view_items_in_registries	An item’s name, description, type and file contents
get_item_examples_from_registries	Demo code such as accordion-demo, with dependencies
get_add_command_for_items	The exact shadcn add command for the items
get_audit_checklist	A fixed six-item checklist: imports, next/image remote patterns, dependencies, lint, TypeScript, and “use the Playwright MCP if available”

The audit checklist is static text, not a scanner. It reminds the agent what to check; it does not inspect your files.

Find, install and compose components with the agent

The workflow that holds up in practice runs in this order: search, view the examples, preview the install, install, then compose and verify. The prompts below encode that order so the agent does not skip the preview.

Copy-paste prompt: find and install the right components

Use the shadcn MCP server. I need a confirmation step before deleting a project and a toast after it succeeds.
1. Check components/ui/ for anything already installed that fits.
2. Search the registry for the missing pieces and show me the examples for each candidate.
3. Get the add command, run it with --dry-run first and list the files it would create or overwrite.
4. Stop and wait for my go-ahead before running it for real.

You should see the agent call search_items_in_registries, then get_item_examples_from_registries and get_add_command_for_items, and then print a --dry-run file list before it stops. If it writes a component without those calls, it ignored the server.

Copy-paste prompt: build a settings form from registry components

Use the shadcn MCP server to view the examples for form, input, select, switch and button, then build src/components/settings-form.tsx:
- fields: name (required), email (valid email), timezone (select), weekly digest (switch)
- validation with the same form library and schema pattern the form example uses
- only components from components/ui/; no hand-written modal, input or toggle
When done, call get_audit_checklist, then run the type check, the linter and the tests, and report each result. Do not report done while any of them fails.

The last line matters: it turns the audit checklist into commands with exit codes rather than a list the agent ticks off from memory.

Pull from a private company registry

Tech leads can publish internal components as a namespaced registry and point every project at it. Add it with the CLI or edit components.json directly:

npx shadcn@latest registry add @acme=https://registry.acme.dev/r/{name}.json

{
  "registries": {
    "@acme": {
      "url": "https://registry.acme.dev/r/{name}.json",
      "headers": { "Authorization": "Bearer ${ACME_REGISTRY_TOKEN}" }
    }
  }
}

The URL must contain the {name} placeholder, and the CLI reads ${ACME_REGISTRY_TOKEN} from the environment, so the token never lands in the file. Replace @acme and the URL with your registry.

Copy-paste prompt: prefer the company registry

Call get_project_registries. For the billing page, search @acme first and use its components wherever one fits; fall back to @shadcn only for pieces @acme does not have, and list which registry each component came from. Show the add commands with --dry-run before installing anything.

How to prove the components work without reading every line

A registry component is vendored code: shadcn add copies it into your repository, and from then on it is yours to test. The gate below lets a reviewer accept the change on evidence.

1. Preview before writing. npx shadcn@latest add alert-dialog --dry-run lists what would change; --diff shows how a local file differs from the registry version. An unexpected overwrite of a customised component stops here.
2. Machine checks. Type check, lint and unit tests must pass in CI, not only in the agent’s summary.
3. Behaviour check. A Playwright test or the agent’s own browser verification opens the page, triggers the dialog and screenshots it. The checklist the server returns asks for the same step.
4. Scope check. git diff --stat should show new files under components/ui/ and your feature file, and nothing else. Changes to globals.css, tailwind.config.* or components.json need a named reason in the pull request.

The reviewer reads the feature file and the evidence, not the vendored primitives. The tech lead who owns components.json signs off on new registries and on version bumps of the pinned CLI.

What the shadcn MCP server costs in context

The seven tool definitions measured about 4.7 KB of JSON schema in tools/list (shadcn 4.21.0, September 2026), roughly 1,200 tokens at four characters per token. That is small next to large vendor servers, but every session pays it. view_items_in_registries returns full file contents, so viewing five components at once can cost far more than the schema. Ask for examples of one component at a time, and see reducing MCP token cost for tool filtering. In Claude Code, run /context before and after enabling the server to see the cost in your own session.

How popular is shadcn/ui?

The shadcn-ui/ui repository, which holds the CLI, the MCP server and the skills, had 124.6k GitHub stars on 2026-09-26 (read from GitHub by the September 2026 ecosystem dossier). Stars measure the whole project, not use of the MCP server; no install figure for the server itself was available.

Which shadcn MCP instructions are wrong or stale?

Traps in older guides and model memory (checked against shadcn 4.21.0, September 2026)

• “mcp init --client codex configures Codex.” It only prints the TOML block. Add [mcp_servers.shadcn] yourself or use codex mcp add.
• npx shadcn diff. The command is deprecated; use npx shadcn@latest add <component> --diff.
• npx shadcn-ui …. shadcn-ui is the old package name; npm marks it deprecated. The package is shadcn.
• “Six tools.” There are seven; get_project_registries is the one older lists miss.
• “The audit checklist scans your components.” It returns fixed text and inspects nothing.
• Svelte, Vue and React Native ports as built-in registries of this server. The server works with @shadcn and the registries in your components.json. Community ports ship their own CLIs; check a port’s docs before assuming the server can install it.

When the shadcn MCP server breaks

The tools fail with a registry fetch error. The server fetches from ui.shadcn.com for the @shadcn registry, and a proxy or firewall that blocks it fails every search. Test with npx shadcn@latest search @shadcn -q dialog in the same shell; if that fails too, allow the host or set the proxy for the client. More in MCP connection issues.

get_project_registries lists no registries. There is no components.json in the directory the server started in. The tool still succeeds with an empty list; @shadcn searches keep working, but any other namespace (such as @acme) fails with Unknown registry. Run npx shadcn@latest init, or start the client from the project root so the server’s working directory is correct.

“Unknown registry @acme”. The namespace is not under registries in components.json. Add it with shadcn registry add, then restart the client so the server rereads the file.

A private registry returns 401. The token variable is unset in the environment the MCP server inherits. Export it before you start the client, or pass it through your client’s MCP env setting; do not paste the token into components.json.

The agent overwrote a customised component. It ran add with --overwrite, or accepted the prompt. Restore the file from git, then keep the “dry run first, wait for my go-ahead” line in your prompts or in CLAUDE.md / AGENTS.md.

The agent still writes custom UI. The server is connected but the agent never calls it. Name the server in the prompt (“use the shadcn MCP server”), or install the shadcn skill, whose instructions tell the agent to search existing components before writing new ones.

Where to go next with shadcn and agents

Figma MCP and design-to-code Map a Figma frame to your shadcn components and prove the build matches it.

Best skills for frontend development The frontend skills worth installing next to the shadcn skill.

Playwright MCP Give the agent a browser to check the components it installed.

MCP servers overview Where the shadcn server fits among the servers a team needs.