What Is shadcn MCP? Letting Your Assistant Search shadcn/ui Components, Setup, Supported Apps and Security

You run one command in your project (`npx shadcn@latest mcp init --client claude`; depending on the client: claude, cursor, vscode, codex, opencode); your coding assistant then searches the component registries defined in your `components.json` file, reads a component's code and examples, and prepares the command needed to add it. It is the shadcn/ui library's own MCP server; MIT licensed, no account, key or fee, and all you need is Node.js and a project with `components.json`. None of the server's seven tools writes files; but when the assistant runs the add command, the component files are written to your project. It has no use for someone who doesn't write code.

What it does: Lets your assistant search shadcn component registries and add components
Type: MCP server (runs on your computer)
Where: Claude Code, Cursor, VS Code, Codex, OpenCode
Requirements: Node.js 20.18.1+ and a project with components.json
Caution: Added component code is written to your project
Latest version: shadcn 4.21.5 (October 14, 2026)
Cost: Free, MIT open source

What is shadcn MCP used for?

MCP is a common standard that lets AI apps connect to outside tools and data; it's how you add new tools to an assistant. You can see other MCPs on the guide's Plugins page. shadcn MCP is a small program built on this standard that opens shadcn/ui's component registries to your assistant.

YouAsk for a component

AssistantClaude Code, Cursor, VS Code, Codex, OpenCode

shadcn MCPRuns on your computer

Component registriesThe registries in components.json

The server writes no files; when the assistant runs the add command, the component is written to your project.

shadcn/ui is a component library (buttons, forms, tables and so on) used by developers who build their own interfaces; its official description is about building your own component library with code you can customize. The catalog where components live is called a registry. When you tell the assistant "add the button, dialog and card components to the project", it can start from the real code in the registry instead of writing the component from scratch.

Search the registry for componentsWhat you get: Item name, type, description and add commandNeeds a separate setup See a component's example codeWhat you get: Full example code and dependenciesNeeds a separate setup Have a component added to your projectWhat you get: Component files written to the project and installed dependenciesNeeds a separate setup

Tool (name in the source code)	What it does	Reads / writes
`get_project_registries`	Returns the registry names defined in components.json.	Reads
`list_items_in_registries`	Lists items in the registries (type filter, pagination).	Reads (from the network)
`search_items_in_registries`	Runs a fuzzy search on item names and descriptions.	Reads (from the network)
`view_items_in_registries`	Shows an item's name, description, type and file contents.	Reads (from the network)
`get_item_examples_from_registries`	Finds usage examples and demos with their full code.	Reads (from the network)
`get_add_command_for_items`	Returns the `shadcn add` command text for adding items; it doesn't run the command itself.	Command text only
`get_audit_checklist`	Gives a checklist after a new component is added.	Reads

The official documentation doesn't list the tools; the seven tools are taken from the mcp/index.ts file in the shadcn-ui/ui repository (raw file, October 15, 2026). None of these seven tools writes files; the files are written by the shadcn add command the assistant runs.

Who it suits: developers who build React interfaces with shadcn/ui and want the assistant to start from real registry code instead of making components up. Who it doesn't suit: people who don't write code; the tool only finds and fetches components from the registry, and the assistant's own model decides what to do with them.

How do you install shadcn MCP?

Installation is a single command in your project folder; the command writes the config file of the app you choose for you. You need: Node.js (the npm package requires 20.18.1 or later), an MCP client and a components.json file in your project. The commands are taken verbatim from the shadcn documentation.

Run in your project› npx shadcn@latest mcp init --client claude

Restart Claude Code.
Type /mcp; if shadcn shows as Connected in the list, you're ready.

Manually: the project's .mcp.json file› { "mcpServers": { "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] } } }

An open issue (#9181) reports that Claude Code expects "type": "stdio" in this config; the documentation example doesn't include that field. If it doesn't work, see the Common issues section.

Run in your project› npx shadcn@latest mcp init --client cursor

Open Cursor Settings and enable the shadcn MCP server.
A green dot and the tool list appear next to the server in the list (documentation).

Manually: the .cursor/mcp.json file› { "mcpServers": { "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] } } }

Run in your project› npx shadcn@latest mcp init --client vscode

Open the .vscode/mcp.json file and click Start next to the shadcn server.
The documentation says to try it with GitHub Copilot.

Manually: the .vscode/mcp.json file (key "servers")› { "servers": { "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] } } }

Documentation: the shadcn command can't update Codex's ~/.codex/config.toml file automatically; you need to add the config manually.

Run in your project› npx shadcn@latest mcp init --client codex

Add to ~/.codex/config.toml

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

Then restart Codex.

Run in your project› npx shadcn@latest mcp init --client opencode

Then restart OpenCode.

OpenCode appears only in the documentation's quick start section, not in the manual configuration section.

The documentation uses shadcn@latest everywhere: the server is tied to the latest published version, not a fixed one. The documentation gives no separate way to pin the version.

How do you use shadcn MCP?

Once connected, you write to the assistant in plain language; it decides on its own which tool to call. The requests below are adapted from the documentation's example prompts; whether they also work when written in another language, such as Turkish, depends on the assistant you connect.

What's in the registry"List the components in the shadcn registry and describe what each one does in one sentence."The documentation's example: "Show me all available components in the shadcn registry".

Add components to your project"Add the button, dialog and card components to my project."The assistant runs the shadcn add command; the files are written to your project. Read the command before it runs.

Build a form from registry parts"Create a contact form using components from the shadcn registry."

To use a private or third-party registry, you add registries to the components.json file. The documentation's example:

components.json

› { "registries": { "@acme": "https://registry.acme.com/{name}.json", "@internal": { "url": "https://internal.company.com/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" } } } }

.env.local (for a private registry; you fill in the value)› REGISTRY_TOKEN=your_token_here

Build a page from a private registry"Build a landing page using the hero, features and testimonials sections from the acme registry."The documentation's example: "Build me a landing page using hero, features and testimonials sections from the acme registry".

The standard shadcn/ui registry needs no extra setup (documentation). For an item in a private registry, write the name as @namespace/component (for example @internal/auth-form).

Which apps does shadcn MCP work with?

The documentation says "you can use it with any MCP client" and shows steps for the most common ones. The table below counts only those named in the documentation as "yes".

Claude CodeYes	The quick start command (`--client claude`) and a project .mcp.json example are in the documentation.
CursorYes	The command (`--client cursor`) and a .cursor/mcp.json example are in the documentation; you enable the server in Cursor Settings.
VS Code (with GitHub Copilot)Yes	The command (`--client vscode`) and a .vscode/mcp.json example are in the documentation.
CodexYes	In the documentation; the config file (~/.codex/config.toml) is edited manually.
OpenCodeYes	Only in the quick start (`--client opencode`); not in the manual configuration section.
Claude Desktop, ChatGPT, Windsurf, Gemini CLI, AntigravityUnclear	Not named in the documentation. "Not in the docs" doesn't mean it won't work; if the app supports adding an MCP server manually, you need to adapt the documented `npx shadcn@latest mcp` command to its config format.

There are open issues for Codex (VS Code extension) and Cursor; see the Common issues section.

What is Claude Code? Detailed guide

What can shadcn MCP access? Security

Reads

Your project's components.json (registry URLs) and the registry files at those URLs: item lists, descriptions, source code and examples. The default registry comes from ui.shadcn.com.

Writes

None of the MCP tools writes files. The mcp init command writes the config file of the app you choose (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json). If the assistant runs the shadcn add command, the registry files are written to your project and dependencies are installed.

Where data goes

The server runs on your computer; it is not a remote service. It sends requests to the registry URLs; for a private registry you send the token in a header. Whether it collects usage data is not stated in the official documentation.

Trust

Component code and dependencies from a third-party or private registry go into your project. Check who runs the registry and review the files that get added. This is general advice; the documentation gives no separate warning.

Security check (October 15, 2026): GitHub Security Advisories (shadcn-ui/ui) shows no entries, and OSV has no record for the shadcn npm package; both sources were checked in full. The repository has a SECURITY.md (private reporting channel). The package has no preinstall, install or postinstall script that runs during installation. No published advisories appear; that does not mean "safe". Because the command uses shadcn@latest, the server is not tied to a fixed version.

Is shadcn MCP free?

Yes. shadcn MCP is an MIT-licensed part of the shadcn package; it requires no account, plan or API key, and the official documentation mentions no fee. The standard shadcn/ui registry works with no extra setup. Private or third-party registries may have their own terms and fees, set by the registry owner. The assistant you connect (Claude Code, Cursor, Copilot, Codex) has its own plan and limits on top. There is no paid plan.

Allowed

MIT: free to use, modify and distribute; keep the copyright and license notice
Can be used in commercial projects

Not allowed

A component from a registry may have its own license; check that registry's license notice before adding it

Source: shadcn-ui/ui LICENSE.md and the npm listing (October 15, 2026). This is not legal advice.

Common issues and fixes

What happens	What to do
The server doesn't respond to requests	The documentation's order: check that the server is configured and enabled in the app, restart the app, confirm shadcn is installed in the project, check network access to the registry URLs.
"No tools or prompts" message	Documentation: run `npx clear-npx-cache`, then re-enable the server in the app. In Cursor, check the "MCP: project-*" log under View › Output.
Components don't come through from the registry	Check the URLs in components.json, the token in .env.local for a private registry, that the registry is online, and the @namespace/component spelling.
A component won't install	Check that there is a valid components.json, that the target folders exist and are writable, and that the dependencies can be installed.
Reported by users Claude Code can't connect via .mcp.json	Open issue #9181 (since December 22, 2025): Claude Code expects "type": "stdio" for the server, which the documentation example doesn't include. No official fix; check the connection with `/mcp`.
Reported by users In a monorepo, components.json in a subfolder isn't found	Open issue #10055 (since March 15, 2026): the MCP has no option like the CLI's `-c`; a private registry gives a "not defined" error.
Reported by users Codex (VS Code extension) doesn't see private registries	Open issue #9730 (since February 25, 2026): only the default @shadcn shows up; according to the reporter, Codex CLI and Claude work fine.

How do you uninstall shadcn MCP?

In the app: Delete the shadcn entry from the config file: .mcp.json in Claude Code, .cursor/mcp.json in Cursor, .vscode/mcp.json in VS Code, the [mcp_servers.shadcn] block in ~/.codex/config.toml in Codex, opencode.json in OpenCode.
If you used a private registry token: Delete the REGISTRY_TOKEN line in .env.local. The registries entries in components.json are settings the CLI uses too; they are not specific to the MCP.
Added components: Component files written to your project are your code and stay. Delete them manually if you don't want them.

The official documentation has no uninstall section; the steps are derived from the files the setup creates.

Frequently asked questions

Which apps does shadcn MCP work with?

The official documentation covers setup for Claude Code, Cursor, VS Code (with GitHub Copilot), Codex and OpenCode, and says it can be used with any MCP client. Apps such as Claude Desktop, Windsurf and Gemini CLI are not mentioned in the documentation; that doesn't mean they won't work.

How do I install shadcn MCP?

You run one command in your project folder depending on your app, for example npx shadcn@latest mcp init --client claude for Claude Code. The command writes the config file; then you restart the app. In Codex the config file is edited manually. You need Node.js and a components.json in your project.

How do I add components from a registry with shadcn MCP?

You write something like "add the button, dialog and card components to my project" to the assistant. The assistant searches the registry, looks at the example and runs the shadcn add command; the files are written to your project. For a private registry, you add registries to the components.json file.

shadcn MCP isn't working. What should I do?

The documentation's order: check that the server is enabled in the app, restart the app, check that shadcn is installed in the project, confirm access to the registry URLs. If you see "No tools or prompts", run npx clear-npx-cache and re-enable the server.

Related guides

shadcn/ui skill

21st MCP

ai-memory awwwards-animations

Brave Search MCP

Chrome DevTools MCP

Sources

Not clear in the official sources: Whether it collects usage data (no statement in the documentation) · official setup steps for Claude Desktop, ChatGPT, Windsurf, Gemini CLI and Antigravity (not in the documentation) · manual configuration for OpenCode (only in the quick start) · Turkish support (the documentation is English only) · uninstall steps (no separate section in the documentation) · the current status of the open issues (whether they have been resolved is unclear in the records). Each is covered in its section.