shadcn/ui in Cursor's agent
Click Add to Cursor, or paste an entry into ~/.cursor/mcp.json, and Cursor's agent checks the registry before it edits your file. It works with Pro: the token in that entry is how the server knows.
- Kind
- Editor
- Goes in
~/.cursor/mcp.json- Connects
- Over HTTP
- Team config
- Yes
- Its docs
- Cursor MCP (opens in a new tab)
Install it with a click
One entry under mcpServers, global to your machine. Signed in with Pro, the config and the Add to Cursor button beside these steps already hold your token.
Click Add to Cursor, or copy the entry
With Pro, the button opens Cursor, which asks before it installs
shadcniowith its header. No token yet? Create one on your account first.Or paste it into ~/.cursor/mcp.json
Add the
shadcniokey insidemcpServers, beside any servers already there, and save. The same file feeds the editor and theagentCLI.Find it in Customize → MCPs
Open Customize in the sidebar, then MCPs (or
Cmd/Ctrl+Shift+P→ Open MCPs). Checkshadcniois switched on; if it isn't listed, restart Cursor.Ask Agent for a component
Open Agent (
Cmd/Ctrl+I) and start withuse shadcnio…the first few times. Depending on your run mode, Cursor asks you or its Auto-review classifier before the first call.
How it reads, with YOUR_TOKEN where your token goes:
{ "mcpServers": { "shadcnio": { "headers": { "Authorization": "Bearer YOUR_TOKEN" }, "url": "https://www.shadcn.io/api/mcp" } } }
~/.cursor/mcp.json sits in your home folder, so the token never enters a repo. If it leaks, regenerate it and paste the new entry.
| Where | Reaches | Shared |
|---|---|---|
~/.cursor/mcp.json | Every project in the editor, and the agent CLI | No: it stays in your home folder |
.cursor/mcp.json in the repo | That project, over a global entry with the same name | Yes: commit it, token from ${env:SHADCNIO_TOKEN} |
| The MCP dropdown at cursor.com/agents (opens in a new tab) | Cloud Agents | Per person; admins add team servers in the dashboard |
Commit it for the whole repo
Commit .cursor/mcp.json with the header read from ${env:SHADCNIO_TOKEN}: Cursor fills it in from each person's environment, so no token lands in git. Each teammate exports their own and restarts Cursor once, and the project entry overrides a global one with the same name. On a Team or Organization plan, each member's own token has Pro.
{ "mcpServers": { "shadcnio": { "headers": { "Authorization": "Bearer ${env:SHADCNIO_TOKEN}" }, "url": "https://www.shadcn.io/api/mcp" } } }
Each teammate sets SHADCNIO_TOKEN to their own token (from their MCP URL), so no token is committed.
See it in Customize
Customize → MCPs lists every server Cursor loaded, yours and the workspace's, each with a toggle; open shadcnio to see its tools one per line.
- Open Customize in the sidebar and pick MCPs.
- Find
shadcnioswitched on, with its 22 tools listed. - In a terminal,
agent mcp listshows it connected too. - Ask the prompt below in Agent: Cursor calls
whoamiand answers with your email, plan and calls left this minute.
What Cursor does with it
The file open in the editor, a Design Mode pick in the Agents Window, and a Cloud Agent that ends in a pull request. Switch the MCP off to see each prompt answered from memory.
- shadcn.io MCP connected · 22 tools
Agent step: Read the selected lines of components/checkout/address-form.tsxReturns: A native select over a long list of countriesMCP call: search_components({ query: "searchable select" })Returns: combobox first, then selectMCP call: get_component({ name: "combobox", include: ["install", "usage"] })Returns: Its npx shadcn add command and a usage exampleAgent step: Ran npx shadcn add in the terminal (Auto-review let it run)Returns: components/ui/combobox.tsx, then the field rewired
In your project
Combobox
- Type to filter, arrow keys to pick
- Still bound to the form's country value
1 prompt → 2 MCP calls
Prompts for Cursor's Agent
For Agent in the editor, the Agents Window or the agent CLI. Naming the server keeps Cursor from guessing among your other MCPs.
Make it fit how you use Cursor
Cursor's run modes, rules, sandbox and Cloud Agents, set so the MCP answers without friction.
Allow its tools in permissions.json
All 22 tools only read the registry. List them in
~/.cursor/permissions.jsonand they run with no prompt and no classifier pass, whilenpx shadcn addstill follows your run mode. The file replaces the MCP allowlist in Settings, so copy over any entries you had there.{ "mcpAllowlist": ["shadcnio:*"] }
A rule for component files
A project rule with
globsattaches itself whenever a matching file is in context, so Agent hears about the registry exactly when it edits UI. Save it as.cursor/rules/shadcn.mdc.--- globs: components/**/*.tsx alwaysApply: false --- Before writing a UI component, search the shadcnio MCP and install what it returns.
Whole pages in Plan Mode
Press
Shift+Tabto rotate to Plan Mode and ask for a page withuse shadcnio:plan_pagelays it out as blocks, each with alternatives. Edit the plan, then build it, andget_blockinstalls the lot in one command.Let installs reach the registry
Under Auto-review,
npx shadcn addruns in Cursor's sandbox, whose default network list doesn't include this site, so a first try can fail and rerun outside it after a review. Add the host from your MCP URL tonetworkPolicy.allowin.cursor/sandbox.jsonto skip the detour.Cloud Agents, set up on the web
Cloud Agents take their servers from the MCP dropdown at cursor.com/agents (opens in a new tab): add
shadcniothere as an HTTP server with the same URL and header. Cursor encrypts the header and proxies each call, so it never sits in the agent's VM.The same server in the CLI
The
agentCLI reads the samemcp.json. List the server's tools to check it, and pass--approve-mcpsso a headless run never waits.$ agent mcp list-tools shadcnio agent -p --approve-mcps "use shadcnio to add a toast when settings save"
When Cursor can't reach it
What you'll see in Cursor, and the fix. Start with MCP Logs in the Output panel; what the server's own error codes mean is in the troubleshooting guide.
shadcniois missing from Customize → MCPs, or shows an error.- Open the Output panel (
Cmd/Ctrl+Shift+U) and pick MCP Logs: broken JSON, a cut-off token or a wrong URL shows there. Fix~/.cursor/mcp.json, save, and restart Cursor. - MCP Logs show a 401 and the tools never load.
- The header holds an old token or none: regenerating it replaces the one in your config. Copy the entry again (or click Add to Cursor again), then switch
shadcniooff and on in Customize → MCPs. - Every shadcnio call in chat comes back failed with a 403.
- Cursor got through, and shadcn.io turned the call down: the account behind the token is no longer on Pro. Renew it, and the same entry works again with nothing to reinstall.
- Your company's MCP Allowlist keeps shadcnio from starting.
- An admin adds a URL entry for the MCP endpoint in Team Settings → MCP Configuration (opens in a new tab). A tool allowlist left empty there lets all 22 tools run.
- A teammate gets 401s from the committed config although SHADCNIO_TOKEN is exported.
- Cursor reads the variable when it starts. Add the export to your shell profile, then quit and reopen Cursor, not just the window.
- The install comes back as npx in a pnpm or Bun project.
- Cursor's default ignore list keeps lockfiles out of Agent's reach, so it can't tell from them. Name the package manager in your prompt or rule, or set
packageManagerin package.json.
Get the MCP for Cursor with Pro
The MCP comes with every Pro plan, with every block and premium template, for you or your whole team. Monthly, yearly or lifetime.
4.9/5 out of 5 · 150+ reviewsfrom 150+ founders and developers.
- Secure checkout via Stripe
- Code lives in your repo
- Keep what you've shipped if you cancel
- License terms
Frequently asked questions
The shadcn MCP in Cursor: setup, limits, and the rest.
From ~/.cursor/mcp.json for every project on your machine, and from .cursor/mcp.json at a repo's root for that project. Cursor merges the two, and the project's entry wins when both use the name shadcnio. The agent CLI reads the same files, so one setup covers the editor and the terminal.
No. It's a cursor:// link: the entry, header included, is base64-encoded inside it and goes from your browser straight to the Cursor app, which asks before it installs the server. Base64 isn't encryption, so treat the link like the token itself and keep it out of public pages.
In the editor and the CLI, yes: give the entry "command": "npx" and "args": ["-y", "mcp-remote", "<your MCP URL>"] in place of url and headers. Keep the url entry if you use Cloud Agents.
Open Customize in the sidebar and pick MCPs: shadcnio should be switched on, with its tools listed one per line. In a terminal, agent mcp list shows it connected too, and agent mcp list-tools shadcnio prints the tools. If the entry is missing, restart Cursor.
Under Auto-review, allowlisted MCP tools run at once and the rest go to its classifier, which may still ask you. Put shadcnio:* in mcpAllowlist in ~/.cursor/permissions.json and every call runs straight away, which is safe because they only read the registry. The installs stay shell commands under your run mode.
Agent chooses among every enabled server's tools by what your prompt asks. Name it (use shadcnio…) or one of its tools, such as search_blocks, and switch off the servers a chat doesn't need in Customize → MCPs. A rule scoped to your component files makes it the default for UI work.
A rule works well for this. A project rule with globs attaches itself whenever a matching file is in context, so Agent hears about the registry exactly when it edits UI. Save it as .cursor/rules/shadcn.mdc.
Press Shift+Tab to rotate to Plan Mode and ask for a page with use shadcnio. The plan_page tool lays the page out as blocks, each with alternatives; edit the plan, then build it, and get_block installs the lot in one command.
Under Auto-review, npx shadcn add runs in Cursor's sandbox, whose default network list leaves this site out, so a first try can fail and rerun outside it after a review. Add the host from your MCP URL to networkPolicy.allow in .cursor/sandbox.json to skip the detour.
Yes. Add shadcnio in the MCP dropdown at cursor.com/agents as an HTTP server with your URL and header; Cursor encrypts the header, redacts it once saved and proxies the calls, so the agent's VM never holds it. The install commands it returns do carry your token in their URL, so regenerate the token if you share a run's output.
As an HTTP server: a url entry with your header, the same as the config on this page. An entry that runs mcp-remote is for the editor and the CLI, so for the web dropdown write it as a plain url entry.
An admin can add it in Team Settings, MCP Configuration, but the server answers as whoever owns the token in its config, so one shared entry puts every teammate's calls on one account and one rate limit. Committing .cursor/mcp.json with ${env:SHADCNIO_TOKEN} keeps each person on their own token, and a Team or Organization plan gives each of them Pro.
Each person exports SHADCNIO_TOKEN from their own shell profile with the token from their account page, then quits and reopens Cursor, because it reads the variable at startup. Teammates on a Team or Organization plan each have their own token, so no one shares a URL.
Only what Cursor's agent puts in each call: a search query, a component or block name, your framework and package manager. The server never opens your files, so .cursorignore has nothing to hide from it. Your code stays with Cursor, which decides what to ask.
In ~/.cursor/mcp.json in your home folder, outside every repo, unless you commit the environment-variable version. It is one-way: the server reads nothing back from your machine. If the token leaks, regenerate it on your account page and the old one stops working within a few minutes.
Open the Output panel and pick MCP Logs: it shows whether the file parsed. Broken JSON, a cut-off token or a wrong URL shows there. Fix the file, save, and restart Cursor.
A 401 means the header holds an old or missing token: copy the entry again and toggle shadcnio off and on. A 403 means the plan behind that token has ended. A 429 means the token made over 600 calls in a minute, so pause for the time Retry-After gives.
Cursor's default ignore list keeps lockfiles out of Agent's reach, so it can't tell the package manager from them. Name it in your prompt or rule, or set packageManager in package.json, and the install comes back as pnpm or bun.
Using another agent too?
The same URL works in every MCP client: use it beside Cursor, in your editor, your terminal or your chat app.
4.9 out of 5 from 150+ developers
Put the registry in Cursor's agent
Add to Cursor once, and Agent works from real components, 6,231 blocks and 294k icons: Pro covers it.
Get Pro