ISSUE 086  ·  17 NOVEMBER 2026 ELEN RSS
CodeCity
DESIGN № 0023

shadcn MCP — your design system becomes a mold in the agent’s hands

shadcn MCP puts the shadcn CLI at your assistant’s service, so it can search, inspect, and install components from the public shadcn/ui registry, from a private design system, or from third-party registries just by asking. We tested it on Windows at zero cost: seven tools, a search that returned 33 results in 0.3 seconds, and one trap, because it needs a real project.

shadcn MCP — το design system σου γίνεται καλούπι στα χέρια του agent

What it does

You know how work slows down when your assistant guesses what a button should look like. It gives you a button from scratch, with its own colors, its own corners, its own height. You throw it away and rewrite it, because your design system says otherwise. shadcn MCP exists to stop that repetition.

I’ll start in plain language, because without that the rest makes no sense. MCP means “model context protocol”: a way to give an AI assistant access to external tools inside the conversation. The assistant does not know them in advance; it discovers them at the start of the session and asks for them when it needs them. shadcn is a set of ready-made components for websites — buttons, dialogs, tables — with one key difference: you do not install them as a library. It copies the code into your own project, and from there on it is yours. A registry is the catalog those components come from.

So the tool puts the shadcn CLI at the agent’s service. The agent gets seven tools and uses them to search within a registry, inspect what is there, read usage examples, and produce the install command. The key point is not the search. It is that you can give it your own registry — meaning your team’s internal design system. Then the agent is not working from a rough example on the web. It is working from your mold.

The seven tools, as the server returned them in our test: get_project_registries, list_items_in_registries, search_items_in_registries, view_items_in_registries, get_item_examples_from_registries, get_add_command_for_items, and get_audit_checklist. The names say what each one does, and that is rare — you do not need a dictionary to read them.

It works with four kinds of catalogs: the public shadcn/ui registry, third-party registries that follow the same spec, private company registries, and multiple registries with a name prefix (@namespace) (documentation).

What it does not do

It does not replace the governance of your design system. It does not sync components back to upstream automatically. When shadcn copies code into the project, it leaves it yours. If you want centralized version control or automatic updates, this is not where you get them.

Do not ask it to create tokens or themes from scratch, or to translate a component between different stacks (for example Tailwind to CSS-in-JS). We tested init in an empty folder and it crashes without tsconfig.json. In Codex you have to edit the config manually. In Cursor you have to enable the server. Those details cost time and errors.

It does not do visual QA, it does not run tests, and it does not guarantee pixel-perfect implementation. The agent suggests commands and code, but human review is still required. The trap we hit is trusting what was copied without checking it again — after that, small mismatches turn into technical debt.

Who it is for

For anyone who has a design system and wants the agent to respect it. If you are working alone on a small site, you will still find it useful, but that is not where it shines: you can write a button by hand too.

It shines in two cases. In a team that has its own components and is tired of explaining them to every assistant again. And for someone working across multiple projects, where each time they have to remember which component fits — there, searching in words instead of browsing folders saves time.

It does not make sense if you work with a design system that does not speak shadcn’s language. The tool lives inside that ecosystem and does not leave it. If your system lives somewhere else, it does not solve your problem.

Installation

Installation happens through the CLI itself, inside your project. You do not download anything by hand.

First, one prerequisite nobody says out loud and we paid for: it needs a real project. If you run the command in an empty folder, it crashes with “Failed to load tsconfig.json”. tsconfig.json is the file that tells TypeScript how to read the project’s code. Without it, the tool has nowhere to work. So you go into your project folder first, then run:

npx shadcn@latest mcp init --client cursor

That is the one step for Cursor. For Claude Code, the same command with a different client name:

npx shadcn@latest mcp init --client claude

Both write a configuration file with the same content, {"mcpServers":{"shadcn":{"command":"npx","args":["shadcn@latest","mcp"]}}} — only the folder changes: .cursor/mcp.json for Cursor, .mcp.json for Claude Code. We saw both files being written in our test.

If you want to do it by hand, that is the exact content, and you place it in your client’s file.

Using it in each LLM

Here the tool behaves differently in each program, and the differences matter. In one, it writes the config for you. In the other, you write it yourself.

Claude Code

Enter your project folder — do not skip this, because otherwise you hit the tsconfig.json error mentioned above — and run:

npx shadcn@latest mcp init --client claude

It writes .mcp.json at the project root. Then restart Claude Code and ask for the list of servers:

claude mcp list

You want to see the line shadcn: Connected. Inside a session, you see the same thing with the /mcp command. If you do not see Connected, most of the time one of two things is wrong: you did not restart, or the config was written in a folder that is not the project (documentation).

Codex CLI

Here the CLI does not help you, and I am not hiding that. The documentation says it plainly: the shadcn CLI cannot update Codex’s ~/.codex/config.toml automatically. You add it by hand.

Open ~/.codex/config.toml and add a section named mcp_servers.shadcn, where you set command = "npx" and args = ["shadcn@latest", "mcp"]. It is the same configuration the CLI writes on its own for the other two clients, in TOML form instead of JSON (documentation).

We did not run this path to the end because we did not have Codex to test it. I am writing it as documentation, not as a measurement, and I am saying that again in the last line.

Cursor

Same start as Claude Code, with one extra step at the end. From the project folder:

npx shadcn@latest mcp init --client cursor

It writes .cursor/mcp.json — we saw that file being created in the test. Then open Cursor settings and enable the shadcn server. That step is not decorative: Cursor does not start the servers on its own just because the file exists. Once it is enabled, you see a green dot next to the name and the list of tools (documentation).

What it costs

In money, nothing. MIT license, no account, no key, no call limit for the public registry — and behind it 48 million downloads per month, so this is not somebody’s experiment. Version 4.21.5, 217 thousand bytes, thirty-three dependencies. The cost is not here.

The real cost is the context, and I measured it myself, not from descriptions: the seven tools of the server load 4,674 characters of definitions — about 1,168 tokens — in every session that has it open. For comparison: ccusage, which measures cost, loads 672 tokens for six tools, while a large enterprise-style MCP server reaches tens of thousands. So this is a reasonable tax, but still a tax: you pay it in every conversation, even when you do not ask for a component.

Then the components themselves. I downloaded them and weighed them: the button is 2,795 bytes, the dialog 4,812, the chart 11,411. In rough token terms, about 700, 1,200, and 2,850 tokens — and a page with ten to fifteen components reaches 4,000 to 10,000 tokens. But you pay that once, and that is where the real difference sits: shadcn does not load a library into your project. It copies the code into your own project. So after the first time, you do not carry a dependency, or breaking upgrades, or a per-session tax. You carry your own code. What you pay in context, you get back in freedom.

One last number, for anyone working with a private registry: that needs REGISTRY_TOKEN in .env.local — infrastructure cost, not a price list. And one practical truth: speed is not the problem; the search returned thirty-three results in three tenths of a second, while the server startup takes about three seconds, once.

Where it wins, where it loses

The first gain is the most important one, and it is not technical: the agent works with your mold, not a rough example. You give the server your own registry, and every component the assistant proposes comes from your own components. That changes the result of the work, not just its speed.

Second, private registries. A team exposes its internal system to the agent and does not have to explain anything again. It needs a REGISTRY_TOKEN in the project’s .env.local and a registry declaration in components.json (documentation) — infrastructure, not magic.

Third, it is fast, free, and accountless. The public registry does not need a key or rate limit, and the search came back in three tenths of a second. There is no trial stage, no card to hand over.

Fourth, seven tools with clear names. You do not need a dictionary to understand what get_add_command_for_items does.

Now where it loses.

First and biggest: it does not compress anything. Every component the agent sees goes into context in full. There is no filter, no summary, no “show me only the part I asked for.” The chart I measured is 11,411 bytes, and if the agent pulls it in to answer a question, you pay for all those bytes.

Second, it needs an existing project. The tsconfig.json trap is not a detail; it is the first thing that happens if you try the tool in an empty folder, as we did.

Third, the private registry takes work. REGISTRY_TOKEN in .env.local, a declaration in components.json, and care not to commit the key.

Fourth, it lives inside the shadcn ecosystem. If your design system is elsewhere — another library, another language, another spec — it does not solve your problem. It is not a tool that adapts to you. You are the one who has to speak its language.

Test

We ran the tool for real, on Windows, at zero cost. No account, no key, no installation. Here is what I saw, in order.

First, installation. The command npx shadcn@latest mcp init –client cursor really wrote .cursor/mcp.json, and the matching one with –client claude wrote .mcp.json. Both with the same content we give in the installation section. So it keeps the first half of the promise: it writes the config, and does not make you copy it yourself.

And the trap, in the same test: when we ran the command in a folder without tsconfig.json, it crashed with “Failed to load tsconfig.json”. I did not discover that in some forum. I saw it happen, and that is why I put it first in installation.

Then the independent test, which I consider the most convincing part. I opened the server by hand, talking to it with JSON-RPC over stdio, and passed the sequence of calls: initialize, notifications/initialized, tools/list, and then a call to search_items_in_registries. The server declared serverInfo with the name shadcn and version 1.0.0. The tools list came back with seven, the names you saw above. And the search with {"registries":["@shadcn"],"query":"button","limit":5} returned 33 items with install commands, in 0.3 seconds. The limit was five; the tool gives you the full match set and not only the first five, which in practice is good and, in context cost, the opposite.

Startup time was measured at 2.9 to 3.8 seconds on initialize. It is the cost you pay once, at the start of the session, and after that the work moves fast.

In Claude Code, the check with claude mcp list and with /mcp inside the session gives the line shadcn: Connected. That is the expected picture; the documentation describes it that way (documentation).

What we did not get to test. I did not set up a private registry to see REGISTRY_TOKEN in live work. What I write about that is documentation. I did not go through Codex, because we do not have Codex on the machine. And the repository numbers — 125,736 stars, 13,392 forks, 1,795 open issues, last push today October 16, 2026 — were read by the research team, together with 48,183,875 npm downloads in thirty days and the 217,215 bytes of version 4.21.5, published on October 14, 2026.

Verdict

shadcn MCP solves a problem you feel before you name it: your assistant builds interfaces that do not resemble your own. It solves it by giving the agent access to your registry, in natural language, for free, without an account.

It is small and honest: seven tools, clear names, one install command, zero money. There is no trial stage to get through, no card to hand over.

The objections are specific. It does not compress anything, so every component enters context in full. It needs a real project, and you learn that from “Failed to load tsconfig.json”. The private registry takes work. And it stays inside the shadcn ecosystem, so it does not solve anything if your design system lives elsewhere.

For anyone who has a design system and works with an agent, the scale leans clearly toward “try it.” The installation is one command inside your project:

npx shadcn@latest mcp init --client cursor

Score: 8.7/10.

See also

Three more from the same category:

Sources:

https://github.com/shadcn-ui/ui

https://www.npmjs.com/package/shadcn

https://ui.shadcn.com/docs/mcp

https://ui.shadcn.com/docs/registry/mcp

https://ui.shadcn.com/docs/registry/authentication

Εγκατάσταση

2 ΒΗΜΑΤΑ
  1. npx shadcn@latest mcp init --client cursor
  2. npx shadcn@latest mcp init --client claude
shadcn MCP — your design system becomes a mold in the agent’s hands · ΑΠΟΤΕΛΕΣΜΑ 8.7/10
ΠΗΓΗ
github.com/shadcn-ui/ui