shadcn MCP Server
Overview
The shadcn MCP server is implemented in packages/…/index.ts and is launched by the mcp CLI command in packages/…/mcp.ts. Running shadcn mcp loads environment files for the selected --cwd, then calls serveStdio(createServer, { onerror }); stdout is reserved for the MCP protocol and transport errors are written to stderr. createServer() builds a per-connection McpServer named shadcn at version 1.0.0, declares fixed tool capabilities with tools.listChanged: false, and registers tools. This server does not register MCP resources or prompts in the covered code.
Each tool callback in packages/…/index.ts is wrapped by registryTool(), which runs the callback inside withRegistryContext(). That wrapper routes GitHub authentication notices through sendGitHubAuthNotice(), writing to stderr and attempting ctx.mcpReq.log("info", message) so registry auth messages can reach MCP clients without contaminating stdout. The same wrapper catches thrown errors and returns MCP tool results with isError: true; RegistryError responses include the registry error code, suggestion, and JSON context when present.
The registered MCP tools are all text-response tools backed by registry APIs:
get_project_registriesreads registry configuration fromgetMcpConfig(process.cwd()), which delegates togetRegistriesConfig(cwd, { useCache: false })in packages/…/utils.ts and returns only theregistriesmap. If no components.json registries are found, the tool returns setup guidance; otherwise it lists registry names and exampleshadcn viewcommands generated bynpxShadcn().list_items_in_registriesaccepts optionalregistries,types,limit, andoffset. It validatestypeswithfindUnknownTypesMessage(), resolves registry names withresolveSearchRegistries(), and callssearchRegistries()withuseCache: false. When no registries are supplied it searches every configured registry and setscontinueOnError: true; skipped registries are appended viaformatSkippedRegistries().search_items_in_registrieshas the same registry/type/pagination handling as the list tool, plus a required fuzzyquery. It formats matches throughformatSearchResultsWithPagination()and appends skipped-registry details when searching all configured registries.view_items_in_registriesaccepts fully prefixed item names such as@shadcn/button, callsgetRegistryItems()with the MCP config anduseCache: false, and formats item metadata withformatRegistryItems(). The formatter reports name, description, type, file count, dependencies, and dev dependencies, but not file contents.get_item_examples_from_registriessearches for demo/example items, fetches the matched full registry items, and returnsformatItemExamples(), which includes file contents intsxcode fences for files that havecontent.get_add_command_for_itemsreturns a runnable package-runner command, usingnpxShadcn("add ...")to pick the local package runner viagetPackageRunner(process.cwd())and pin the CLI invocation toshadcn@latest.get_audit_checklistreturns a static checklist for reviewing generated components.
The CLI also exposes shadcn mcp init in packages/…/mcp.ts to configure supported clients. It accepts --client or prompts with prompts for claude, cursor, vscode, codex, or opencode. For Claude Code, Cursor, VS Code, and OpenCode, runMcpInit() ensures the target config directory exists, attempts to parse an existing JSON config, deep-merges the client-specific MCP server entry with array replacement, and writes the JSON file with a trailing newline. The configured command is npx shadcn@latest mcp for JSON-based clients, with VS Code using a servers key and the others using their client-specific mcpServers or mcp keys. For Codex, mcp init does not write the TOML path listed in CLIENTS; instead it installs shadcn@latest and prints instructions for manually adding [mcp_servers.shadcn] to ~/…/config.toml.
Dependency installation during mcp init depends on whether getConfig(options.cwd) finds an existing shadcn project config. If it does, updateDependencies([], ["shadcn@latest"], config, { silent: false }) is used. If not, the command detects the package manager with getPackageManager(options.cwd) and runs either npm install --save-dev shadcn@latest or <pm> add -D shadcn@latest through execa in the selected cwd.
packages/…/utils.test.ts covers the MCP formatting helpers rather than the server transport. It asserts add-command rendering, pagination wording, type validation, skipped-registry messages, metadata formatting, and example code-fence behavior.
Coupling
- If the registry search type set changes, update or verify
findUnknownTypesMessage()in packages/…/utils.ts and the schemas in packages/…/index.ts; MCP tools reject unknowntypesbefore callingsearchRegistries(), so drift fromSEARCHABLE_TYPESblocks otherwise valid registry queries. - If
searchRegistries()changes its pagination or error shape, verifyformatSearchResultsWithPagination()andformatSkippedRegistries()in packages/…/utils.ts;list_items_in_registriesandsearch_items_in_registriesconcatenate these strings directly into user-facing MCP responses. - If MCP client config formats change, update the
CLIENTSentries andrunMcpInit()behavior in packages/…/mcp.ts; JSON clients are deep-merged into existing files, while Codex is only printed as manual TOML instructions despite having aCLIENTSconfig entry. - If the server transport or logging changes, preserve the stdout/stderr split in packages/…/mcp.ts and
sendGitHubAuthNotice()in packages/…/index.ts; stdio MCP clients expect protocol frames on stdout, while GitHub auth notices and transport errors must not be emitted there as plain text.
Risks
- packages/…/index.ts and packages/…/utils.ts recently had a fix for awaiting generated add commands (
fix(mcp): await the add command in search and list resultsin git history). If new formatting paths callnpxShadcn()without awaiting it, MCP responses can expose[object Promise]or otherwise invalid commands. - packages/…/mcp.ts parses existing non-Codex client config as JSON and silently falls back to
{}on any read or parse error. If a supported client changes to a non-JSON format, or if an existing JSON config is malformed,mcp initcan overwrite the target file with only the generated MCP configuration.