1# shadcn MCP Server
2 
3The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
4 
5---
6 
7## Setup
8 
9```bash
10shadcn mcp        # start the MCP server (stdio)
11shadcn mcp init   # write config for your editor
12```
13 
14Editor config files:
15 
16| Editor      | Config file                     |
17| ----------- | ------------------------------- |
18| Claude Code | `.mcp.json`                     |
19| Cursor      | `.cursor/mcp.json`              |
20| VS Code     | `.vscode/mcp.json`              |
21| OpenCode    | `opencode.json`                 |
22| Codex       | `~/.codex/config.toml` (manual) |
23 
24---
25 
26## Tools
27 
28> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
29 
30### `shadcn:get_project_registries`
31 
32Returns registry names from `components.json`. Errors if no `components.json` exists.
33 
34**Input:** none
35 
36### `shadcn:list_items_in_registries`
37 
38Lists all items from one or more registries. Registries can be configured
39namespaces such as `@acme`, public GitHub sources such as `owner/repo`, or
40registry catalog URLs. Omit `registries` to list from every registry configured
41in `components.json`.
42 
43**Input:** `registries` (string[], optional — omit for all configured), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
44 
45### `shadcn:search_items_in_registries`
46 
47Fuzzy search across registries. Registries can be configured namespaces, public
48GitHub sources, or registry catalog URLs. Omit `registries` to search every
49registry configured in `components.json` — e.g. "find me a hero" across all
50configured registries.
51 
52**Input:** `registries` (string[], optional — omit for all configured), `query` (string), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
53 
54### `shadcn:view_items_in_registries`
55 
56View item details including full file contents.
57 
58**Input:** `items` (string[]) — e.g.
59`["@shadcn/button", "@shadcn/card", "owner/repo/item"]`
60 
61### `shadcn:get_item_examples_from_registries`
62 
63Find usage examples and demos with source code. Omit `registries` to search
64every registry configured in `components.json`.
65 
66**Input:** `registries` (string[], optional — omit for all configured), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
67 
68### `shadcn:get_add_command_for_items`
69 
70Returns the CLI install command.
71 
72**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
73 
74### `shadcn:get_audit_checklist`
75 
76Returns a checklist for verifying components (imports, deps, lint, TypeScript).
77 
78**Input:** none
79 
80---
81 
82## Configuring Registries
83 
84Namespaced and authenticated registries are set in `components.json`. The
85`@shadcn` registry is always built-in. Public GitHub registries can also be used
86directly as `owner/repo` registry sources when the repository has a root
87`registry.json`; they do not need `components.json` configuration.
88 
89```json
90{
91  "registries": {
92    "@acme": "https://acme.com/r/{name}.json",
93    "@private": {
94      "url": "https://private.com/r/{name}.json",
95      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
96    }
97  }
98}
99```
100 
101- Names must start with `@`.
102- URLs must contain `{name}`.
103- `${VAR}` references are resolved from environment variables.
104 
105Community registry index: `https://ui.shadcn.com/r/registries.json`
106