Skip to content

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

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.

  1. Click Add to Cursor, or copy the entry

    With Pro, the button opens Cursor, which asks before it installs shadcnio with its header. No token yet? Create one on your account first.

  2. Or paste it into ~/.cursor/mcp.json

    Add the shadcnio key inside mcpServers, beside any servers already there, and save. The same file feeds the editor and the agent CLI.

  3. Find it in Customize → MCPs

    Open Customize in the sidebar, then MCPs (or Cmd/Ctrl+Shift+P → Open MCPs). Check shadcnio is switched on; if it isn't listed, restart Cursor.

  4. Ask Agent for a component

    Open Agent (Cmd/Ctrl+I) and start with use shadcnio… the first few times. Depending on your run mode, Cursor asks you or its Auto-review classifier before the first call.

~/.cursor/mcp.json
Sign in to get your config
Sign in with a Pro account, and this holds your MCP URL, ready to paste.

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 Cursor picks the server up
WhereReachesShared
~/.cursor/mcp.jsonEvery project in the editor, and the agent CLINo: it stays in your home folder
.cursor/mcp.json in the repoThat project, over a global entry with the same nameYes: commit it, token from ${env:SHADCNIO_TOKEN}
The MCP dropdown at cursor.com/agents (opens in a new tab)Cloud AgentsPer 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.

.cursor/mcp.json
{
  "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.

  1. Open Customize in the sidebar and pick MCPs.
  2. Find shadcnio switched on, with its 22 tools listed.
  3. In a terminal, agent mcp list shows it connected too.
  4. Ask the prompt below in Agent: Cursor calls whoami and answers with your email, plan and calls left this minute.
Prompt
use shadcnio's whoami: which plan am I on, and how many calls are left?

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.

Your agent
  1. shadcn.io MCP connected · 22 tools
  2. You: Make the country field in this form searchable.
  3. Agent step: Read the selected lines of components/checkout/address-form.tsxReturns: A native select over a long list of countries
  4. MCP call: search_components({ query: "searchable select" })Returns: combobox first, then select
  5. MCP call: get_component({ name: "combobox", include: ["install", "usage"] })Returns: Its npx shadcn add command and a usage example
  6. Agent step: Ran npx shadcn add in the terminal (Auto-review let it run)Returns: components/ui/combobox.tsx, then the field rewired
  7. Your agent: The country field is a combobox now: type to filter, Enter to pick, the same form value as before.

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.

01
use shadcnio to turn the select in this file into a searchable combobox
02
use shadcnio to plan a landing page for our invoicing app, then build it from blocks
03
use shadcnio to show an empty state in the invoices table when a filter matches nothing
04
use shadcnio to swap the emoji in the sidebar nav for icons from our Lucide set
05
use shadcnio to look up Popover's positioning props before changing the account menu
06
use shadcnio to give the app Vercel's look from its DESIGN.md, saved at the root
07
use shadcnio to get this Nuxt project ready for shadcn-vue components

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.json and they run with no prompt and no classifier pass, while npx shadcn add still 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 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.

    ---
    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+Tab to rotate to Plan Mode and ask for a page with use shadcnio: plan_page lays it out as blocks, each with alternatives. Edit the plan, then build it, and get_block installs the lot in one command.

  • Let installs reach the registry

    Under Auto-review, npx shadcn add runs 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 to networkPolicy.allow in .cursor/sandbox.json to 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 shadcnio there 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 agent CLI reads the same mcp.json. List the server's tools to check it, and pass --approve-mcps so 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.

shadcnio is 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 shadcnio off 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 packageManager in 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.

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