Introducing a new way to review your PRs.

Read the announcement

shadcn-ui / ui

Composable, accessible components with thoughtful defaults. Build your own component library with code you can customize, extend, and make your own.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / shadcn-mcp-server

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_registries reads registry configuration from getMcpConfig(process.cwd()), which delegates to getRegistriesConfig(cwd, { useCache: false }) in packages/…/utils.ts and returns only the registries map. If no components.json registries are found, the tool returns setup guidance; otherwise it lists registry names and example shadcn view commands generated by npxShadcn().
  • list_items_in_registries accepts optional registries, types, limit, and offset. It validates types with findUnknownTypesMessage(), resolves registry names with resolveSearchRegistries(), and calls searchRegistries() with useCache: false. When no registries are supplied it searches every configured registry and sets continueOnError: true; skipped registries are appended via formatSkippedRegistries().
  • search_items_in_registries has the same registry/type/pagination handling as the list tool, plus a required fuzzy query. It formats matches through formatSearchResultsWithPagination() and appends skipped-registry details when searching all configured registries.
  • view_items_in_registries accepts fully prefixed item names such as @shadcn/button, calls getRegistryItems() with the MCP config and useCache: false, and formats item metadata with formatRegistryItems(). The formatter reports name, description, type, file count, dependencies, and dev dependencies, but not file contents.
  • get_item_examples_from_registries searches for demo/example items, fetches the matched full registry items, and returns formatItemExamples(), which includes file contents in tsx code fences for files that have content.
  • get_add_command_for_items returns a runnable package-runner command, using npxShadcn("add ...") to pick the local package runner via getPackageRunner(process.cwd()) and pin the CLI invocation to shadcn@latest.
  • get_audit_checklist returns 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 unknown types before calling searchRegistries(), so drift from SEARCHABLE_TYPES blocks otherwise valid registry queries.
  • If searchRegistries() changes its pagination or error shape, verify formatSearchResultsWithPagination() and formatSkippedRegistries() in packages/…/utils.ts; list_items_in_registries and search_items_in_registries concatenate these strings directly into user-facing MCP responses.
  • If MCP client config formats change, update the CLIENTS entries and runMcpInit() behavior in packages/…/mcp.ts; JSON clients are deep-merged into existing files, while Codex is only printed as manual TOML instructions despite having a CLIENTS config 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 results in git history). If new formatting paths call npxShadcn() 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 init can overwrite the target file with only the generated MCP configuration.