shadcn MCP: install UI components from Claude Code and Cursor
Set up the shadcn MCP server and CLI in Claude Code, Cursor or VS Code, add a private registry and install components by prompt, plus the hosted mebius MCP.
The shadcn CLI has an MCP server built in, so Claude Code, Cursor and VS Code can browse and install registry components for you. Here is the setup for each editor, how to add a private registry, and the errors you will hit and what they mean.
shadcn’s MCP server is built into the shadcn CLI. Run npx shadcn@latest mcp init --client claude, or --client cursor, and your AI editor can browse, search and install items from every registry in components.json. mebius.design adds a hosted MCP server that returns each item’s full source and usage docs.
What is the shadcn MCP server?
Checked in shadcn’s docs and source on 17 Nov 2026.
The shadcn MCP server is part of the shadcn CLI, the MIT-licensed shadcn package on npm (4.23.0 when we checked). Your editor starts it on your own machine with npx shadcn@latest mcp, and the AI can then browse, search and install items from any registry in your components.json: shadcn/ui’s own (no setup needed), third-party registries, private ones behind a token, and namespaced ones such as @acme. See shadcn’s MCP docs.
Under the hood it has seven tools (source): list the registries in components.json; list, search and view registry items with their files; find usage examples; return the shadcn add command for chosen items; and a checklist to run after new code is written. The server doesn’t write files itself. The assistant runs the add command it gets back, so every install still goes through the CLI.
How do you set up shadcn MCP?
One command per editor, then a restart.
Run init in your project with the name of your editor. It adds the shadcn server to that editor’s MCP config:
Terminal:
npx shadcn@latest mcp init --client claude
# or --client cursor, vscode, codex or opencode
Restart the editor afterwards. In Claude Code, run /mcp and check that shadcn shows as connected; in Cursor, turn the server on in Cursor Settings; in VS Code, open .vscode/mcp.json and click Start. Codex is the exception: the CLI can’t edit ~/.codex/config.toml, so you add the server there by hand. Written by hand for Claude Code, the server is this file:
.mcp.json:
{
"mcpServers": {
"shadcn": {
"command": "npx",
"args": ["shadcn@latest", "mcp"]
}
}
}
Cursor takes the same block in .cursor/mcp.json; VS Code puts it under "servers" in .vscode/mcp.json. If the editor lists no tools, shadcn’s troubleshooting notes suggest clearing the npx cache (npx clear-npx-cache) and switching the server off and on again.
How do you add a private registry?
Once per project. The example is the @mebius registry.
A private registry is a namespace in components.json: a URL template the CLI fills with the item name and, when the registry needs one, a header that reads a token from your environment (shadcn’s authentication docs). The CLI and its MCP server both read it. For mebius.design, create a token in Settings › Tokens (a free account works) and add:
components.json:
{
"registries": {
"@mebius": {
"url": "https://www.mebius.design/r/{name}.json",
"headers": {
"Authorization": "Bearer ${MEBIUS_TOKEN}"
}
}
}
}
.env.local:
MEBIUS_TOKEN=mbs_your_token
Keep the token out of git. The CLI reads .env.local and .env. Check that .env.local is in your .gitignore, and revoke a token in Settings › Tokens if it leaks.
Each mebius kit has a theme item. Add it on its own first, then items with --overwrite so shared parts take the kit’s version. Item names start with their kit:
Terminal:
npx shadcn@latest add @mebius/charts-theme
npx shadcn@latest add @mebius/charts-revenue-growth --overwrite
No token yet? The 20 open starter items install from their URL with no account, like the Revenue Overview chart: npx shadcn@latest add https://www.mebius.design/r/charts-revenue-overview.json.
Which shadcn CLI commands matter?
What the MCP server asks for, and what you can run yourself.
When an agent gets stuck, the same work runs in a terminal. From shadcn’s CLI docs, the commands that matter for registries:
init: creates components.json, adds the cn helper and sets up CSS variables. Once per project.add: installs items by name, @namespace/name or URL.--overwritereplaces files that already exist,--dry-runpreviews the changes.view: prints an item’s files before you install it.search(aliaslist): searches one or more registries, with-qfor a query.info: shows your project’s setup as the CLI sees it, handy when an install lands in the wrong folder.
With the @mebius registry set up, you can find, read and install a chart without leaving the terminal:
Terminal:
npx shadcn@latest search @mebius -q "candlestick"
npx shadcn@latest view @mebius/charts-ethereum
npx shadcn@latest add @mebius/charts-ethereum --overwrite
What does the mebius MCP server add?
A hosted server with browser sign-in and usage docs per item.
mebius.design runs its own MCP server at https://www.mebius.design/api/mcp. Nothing runs on your machine and it doesn’t need a components.json: it reads the kits your account has and returns each item’s source files with their target paths, its npm and registry dependencies, and the usage docs written for that component or block (props, examples, notes). As of 17 Nov 2026, a free account gets all 62 free charts and 128 free forms; buying a kit adds that kit, and All items adds every kit.
In Claude Code, add it with one command, with no token to copy:
Terminal:
claude mcp add --transport http mebius https://www.mebius.design/api/mcp
Then run /mcp, pick mebius, choose Authenticate, log in to mebius.design in the browser and click Approve. Cursor and VS Code ask you to log in the first time they connect:
.cursor/mcp.json:
{
"mcpServers": {
"mebius": {
"url": "https://www.mebius.design/api/mcp"
}
}
}
VS Code takes the same URL under "servers" with "type": "http". Tools that can’t open a browser, like CI or a remote machine, send a token from Settings › Tokens as the header Authorization: Bearer <your token>. The server has five read-only tools:
list_kits: the kits your account has, the free ones included, with item counts and categories, and the paid kits it doesn’t own yet.list_itemsandsearch_items: find a component or block by kit, type, category or plain words.get_item: one item in full, with every file, its dependencies and its usage docs.get_install_instructions: the components.json entry, the token line and the exact add commands, theme first.
Which MCP server should you use?
Both, for different jobs.
- shadcn MCP: local, free and MIT, and it works with every registry in components.json, shadcn/ui’s own included. Best for browsing many registries and installing through the CLI.
- mebius MCP: hosted, signs in through the browser and covers mebius kits only. Best when the agent should read an item’s usage docs before it adapts a block, or write the files by hand in a project without components.json.
They don’t clash. With the @mebius registry in components.json, shadcn’s server lists mebius items too, and a prompt like “add the mebius candlestick chart to the dashboard” ends the same way with either one: the theme, then npx shadcn@latest add @mebius/charts-ethereum --overwrite.
Other marketplaces run their own servers too: the UI8 MCP at https://mcp.ui8.net/mcp is included with UI8’s All Access pass (checked on ui8.net on 17 Nov 2026). How the two marketplaces compare overall is in mebius vs UI8.
What if the CLI or MCP says no?
The mebius registry answers with a message the CLI prints.
- No mebius token was sent: MEBIUS_TOKEN isn’t set where the CLI runs, or the registry URL redirects. Use the exact https://www URL above.
- The token is invalid or has been revoked: create a new one and replace the line in .env.local.
- Your account doesn’t own this kit: the item belongs to a paid kit. Buy it for $19, or All items for $259, and run the command again.
- No item with that name: item names start with their kit, like @mebius/charts-ethereum.
npx shadcn@latest search @mebiuslists the ones your token can install.
The free items are the quickest test of the whole setup: create a free account and every chart and form is yours to install, by command or by prompt.
FAQ
Is the shadcn MCP server free?
Yes. It is part of the shadcn CLI, which is MIT licensed and free. It runs on your machine through npx, so it needs no account or key, apart from any tokens your private registries ask for.
Does the shadcn MCP server work with private registries?
Yes. Add the registry to components.json under a namespace, with an Authorization header that reads a token from an environment variable, and put the token in .env.local. The CLI and the MCP server both read it.
What is the difference between the shadcn CLI and shadcn MCP?
The CLI is the command-line tool that sets up a project and adds, views and searches registry items. The MCP server lets an AI editor do the same by prompt: it looks items up in your registries and hands the assistant the add command to run.
Do I need a token for the mebius MCP server?
No. Claude Code, Cursor and VS Code sign in through the browser: add the server, log in to mebius.design and click Approve. A personal access token from Settings › Tokens is the fallback for tools that can’t open a browser, and the shadcn CLI needs one for the @mebius registry.
Can an AI editor install mebius components without an account?
Only the 20 open starter items, which install from their URL with the plain shadcn CLI. The MCP server needs a sign-in, and a free account covers all 62 charts and 128 forms.
Related
- Free charts: 62 animated chart cards to install with the commands above.
- Free forms: 128 animated forms in light and dark.
- Is shadcn/ui free?: The MIT license, and what free and paid shadcn kits allow.
- Figma to React: How the registry behind these commands is made from Figma.
First published on mebius.design, where the code samples stay up to date.
About the author
- I design and build mebius.design: Figma UI kits for dashboards, mobile apps and websites with matching React + Tailwind code for shadcn, installable with the shadcn CLI or over MCP. Free animated charts and forms at https://www.mebius.design
Comments
Join the discussionNo comments yet. Be the first to comment.
