Skip to content

shadcn.io MCP prompt

Rules that make your agent use the shadcn.io MCP server well: search first, install the right component for your framework and UI library, and keep your token out of the code.

What it makes your agent good at

An agent with an MCP server it doesn't know calls the wrong tool, installs a Radix component into a Base UI project, or retypes a component from memory and leaks the install token into a commit. This prompt gives it the server's working order: pick the target, search, install with one call, use the docs it returns.

  1. The right target, every callReact, Vue, Svelte or Solid from package.json, and for React the primitives already there: Base UI, Radix, React Aria or Ark UI.
  2. Search before it writessearch_components, search_demos, search_blocks and plan_page before writing a line of UI by hand.
  3. One call, one installget_component with install and usage, names for several, have so edited files stay put.
  4. Your token stays privateThe install URL's token stays in the command: never printed in full, committed or stripped.
  5. Docs from the serverget_component_api and get_demo instead of guessing props, and each base's own composition: render, asChild or render props.
  6. Honest about limitsPro items named as Pro, rate limits reported, never a block rebuilt from memory and passed off as the real one.

The shadcn.io MCP rules

65 lines, current to the shadcn.io MCP server's 22 tools. Last reviewed October 23, 2026. Plain Markdown, no front matter: each agent's is below.

Download

shadcn-mcp.md

# shadcn.io MCP

You are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.

## Before you call anything

- Pick the target from `package.json`, once, and pass it on every call:
  - `framework`: `react`, `vue`, `svelte` or `solid`.
  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.
  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.
- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.
- Read the lockfile for the package manager and pass it as `packageManager`.
- No `components.json` yet: call `get_project_setup` once (for React pass `stack`: `next`, `vite`, `tanstack-start`…, and `existing: true` for an app that already exists), run what it returns, then add components. Never run init again in a configured project.

## Find before you write

- A component: `search_components` with what it does ("date range", "modal", "toast"); shadcn/ui's names and other spellings find ours. `list_components` is the catalog by category.
- A pattern inside components ("controlled dialog", "combobox with groups", "form in a sheet"): `search_demos`, across every demo.
- A section or a screen (a pricing table, a settings page, a kanban board): `search_blocks` by what it does, or `list_blocks` by category. A whole page: `plan_page` with a one-line `brief` (and `kind`: `marketing` or `app`), then `get_block` with the picks' `names`.
- A brand's look ("like Linear", "a dark fintech"): `search_designs`, then `get_design`. Save its Markdown as `DESIGN.md` at the project's root and set the theme's tokens from it.
- A new app: `search_templates` may already have most of it.
- Icons: use the set the project has (`lucide-react`, `@tabler/icons-react`…). `search_icons` with `library` and several `queries` in one call, then `get_icon` with `names`: a set with a package returns the import, nothing to install.
- Ask for exactly what you need: one search with a good query beats three vague ones. Use `limit`.

## Install, don't paste

- `get_component` with `include: ["install", "usage"]` gives the command and a usage snippet in one call. Add `"demo"` or `"api"` only when you need them. Several components for one feature: pass `names` and get one install for all of them.
- Run the install command exactly as returned: React and Solid use the shadcn CLI, Vue `shadcn-vue`, Svelte `shadcn-svelte`. The URL carries the user's registry token: never print it in full, write it into source files, logs or commits, or strip it.
- No shell, or the user wants to review first: `get_install_plan` (with `have` and `packageManager`) returns every file, package and CSS change. Write the files at the project's aliases; a long plan names the rest in `pending`: request those as `files`.
- Blocks are part of Pro: `get_block` with `include: ["install"]`, `names` for a whole page in one command. If the server says an item needs Pro, tell the user; do not rebuild the block from memory and present it as the real one.
- After an install, import from the project's ui alias (`@/components/ui/dialog`), and check `usageNeeds`: a component the usage snippet imports that the install did not bring.

## Use components as their docs say

- Props and parts come from the server, not from memory: `get_component_api` for an outline (`part` or `prop` for one in full), `get_component_docs` with `sections` for the prose you need, `get_demo` for another demo (pass `uiAlias` from `components.json`, so its imports point at the project's folder).
- Follow the base's composition model and never mix them: Base UI merges onto a host with `render`, Radix and Ark UI with `asChild`, React Aria with render props and its own event names (`onPress`, `isDisabled`).
- Ark UI's Select, Combobox and Listbox take a `collection` built with its helpers, not a loose `items` array; follow the demo.
- Forms, theming, colors and RTL: `get_guide`. Each form field type has a demo per form library: `get_demo` with `name` `react-hook-form`, `tanstack-form` or `formisch`.
- Keep what the installed files give you: `data-slot` attributes, labels, focus handling and keyboard behavior. Extend a component with a prop or a wrapper; edit its file only for a change the whole project should get.

## Style it with the project's theme

- Use the theme's tokens (`bg-background`, `text-muted-foreground`, `border-input`, `bg-primary`), never palette classes (`gray-500`) or hex values. Dark mode follows from the tokens.
- Respect the project's radius, fonts and spacing; when a `DESIGN.md` exists, follow it.
- Layout with flex or grid and `gap-*`; logical properties (`ms-*`, `pe-*`, `start-*`) so RTL works.
- Icons: decorative ones get `aria-hidden="true"` and a `size-*` class, not a numeric `size` prop.

## Calls and limits

- Prefer one call with `include` or `names` to several round trips; the answers stay small unless you ask for source.
- When several MCP servers are connected, the user names this one ("use shadcnio to…"); for UI work, prefer it to guessing.
- `whoami` shows who is connected and the rate limit. If a call is rate limited or unauthorized, say so and stop; do not fall back to scraping the site.

## Do not

- Do not hand-write a component, block or icon the server has, or copy one from another registry from memory.
- Do not install for the wrong target: a Radix component into a Base UI project, a React file into a Svelte one.
- Do not invent registry URLs or item names: use the names and commands the tools return.
- Do not install the whole catalog "to be safe": add what the task needs.
- Do not overwrite files the user changed: pass `have`, and read a diff before accepting an overwrite prompt.

## Before you finish

- Run the project's type check and linter, and open the page you changed.
- List what you installed (components, blocks, icons), the commands you ran, and anything that needed Pro or a setup step the user still has to do.

6,664 characters, 1,086 words. Under Windsurf's 12,000-character limit for a rule, as every prompt here is.

Use it in your agent

The same rules, where your agent reads them. Each file has the front matter its agent needs, set to apply on every request.

Claude Code

A rule it loads every session

  1. Save it as .claude/rules/shadcn-mcp.md in your project, front matter included, or run the install command.
  2. Claude Code loads every file in .claude/rules with your CLAUDE.md when a session starts.
  3. Prefer one file? Paste it into CLAUDE.md under its own heading instead.

.claude/rules/shadcn-mcp.md

# shadcn.io MCPYou are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.## Before you call anything- Pick the target from `package.json`, once, and pass it on every call:  - `framework`: `react`, `vue`, `svelte` or `solid`.  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.- Read the lockfile for the package manager and pass it as `packageManager`.…

Or let the shadcn CLI write this file: sign in (free) for your command.

Cursor

A project rule with front matter

  1. Save it as .cursor/rules/shadcn-mcp.mdc, front matter included, or run the install command.
  2. alwaysApply: true adds it to every Agent request in this project.
  3. Check it under Cursor Settings, Rules, then commit the folder for your team.

.cursor/rules/shadcn-mcp.mdc

---description: "Working with the shadcn.io MCP server: finding, installing and using its components, blocks, icons and design systems."alwaysApply: true---# shadcn.io MCPYou are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.## Before you call anything- Pick the target from `package.json`, once, and pass it on every call:  - `framework`: `react`, `vue`, `svelte` or `solid`.  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.- Read the lockfile for the package manager and pass it as `packageManager`.…

Or let the shadcn CLI write this file: sign in (free) for your command.

Windsurf

A workspace rule for Cascade

  1. Save it as .windsurf/rules/shadcn-mcp.md, or run the install command.
  2. trigger: always_on applies it to every Cascade request in this workspace.
  3. Windsurf reads up to 12,000 characters per rule; this one is 6,664.

.windsurf/rules/shadcn-mcp.md

---trigger: always_on---# shadcn.io MCPYou are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.## Before you call anything- Pick the target from `package.json`, once, and pass it on every call:  - `framework`: `react`, `vue`, `svelte` or `solid`.  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.- Read the lockfile for the package manager and pass it as `packageManager`.…

Or let the shadcn CLI write this file: sign in (free) for your command.

GitHub Copilot

Instructions for the repository

  1. Save it as .github/instructions/shadcn-mcp.instructions.md, or run the install command.
  2. applyTo: "**" applies it to every request in this repository.
  3. Or paste it into .github/copilot-instructions.md, which Copilot reads for every request.

.github/instructions/shadcn-mcp.instructions.md

---description: "Working with the shadcn.io MCP server: finding, installing and using its components, blocks, icons and design systems."applyTo: "**"---# shadcn.io MCPYou are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.## Before you call anything- Pick the target from `package.json`, once, and pass it on every call:  - `framework`: `react`, `vue`, `svelte` or `solid`.  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.- Read the lockfile for the package manager and pass it as `packageManager`.…

Or let the shadcn CLI write this file: sign in (free) for your command.

Codex & AGENTS.md

The file most agents read

  1. Paste it into AGENTS.md at your project's root, under its own heading.
  2. Codex reads AGENTS.md before it starts work, and so do Cursor, Zed, Jules, Amp and Copilot's coding agent.
  3. A folder can have its own AGENTS.md: the one closest to the file being edited wins.

AGENTS.md

## shadcn.io MCPYou are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.### Before you call anything- Pick the target from `package.json`, once, and pass it on every call:  - `framework`: `react`, `vue`, `svelte` or `solid`.  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.- Read the lockfile for the package manager and pass it as `packageManager`.…

AGENTS.md is shared with your own instructions, so paste the rules in: the copy sets their headings a level down.

Rules teach it. The MCP equips it. With Pro, your agent installs every component, block and icon it needs, from a prompt.

Get Pro

Pricing

Give your agent the parts, with Pro

The prompts are free. Every Pro plan adds the MCP server, so your agent installs the components, blocks and icons it writes code around.

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

shadcn.io MCP prompt FAQ

What the shadcn.io MCP prompt covers and how to use it in your agent.

How does the shadcn.io MCP prompt pick the framework and UI library?

From package.json: the framework (React, Vue, Svelte or Solid), and for React the primitives the project already uses: Base UI, Radix, React Aria or Ark UI, with Base UI as the default when there are none. The prompt has the agent pass both on every call, so an install never brings a second primitive library.

Does the agent run the install command or write the files?

It runs the command the server returns as it is: the shadcn CLI for React and Solid, shadcn-vue for Vue, shadcn-svelte for Svelte. Without a shell, the prompt has the agent call get_install_plan and write the files at the project's aliases.

What does the shadcn.io MCP prompt do with my registry token?

The install URL carries the user's registry token, so the prompt forbids printing it in full, writing it into source files or commits, or stripping it from the command. The token stays in the command the agent runs and nowhere else.

Will the agent overwrite components I've edited?

It passes what the ui folder already holds as have, so an install leaves edited files alone, and it never runs init again in a configured project. When the CLI still asks before overwriting, the agent reads the diff first.

4.9 out of 5 from 150+ developers

Rules teach it. The MCP equips it.

Every component, block and icon, installed by your AI agent on your stack. The prompts stay free.

Get Pro
  • Cancel anytime
  • Keep what you've shipped