OpenWikishadcn-ui/ui

MCP Overview

Purpose and Scope

The shadcn MCP Server connects AI assistants to shadcn-compatible registries so a developer can ask for components, examples, and project changes in natural language instead of manually browsing registry indexes. The user-facing docs introduce the server as a way to browse available components, search for specific ones, and install them into the current project. In practice, the server sits between an MCP-capable client and the existing shadcn registry system, using the project’s registry configuration as the source of truth for which component catalogs are available.

Sources: apps/v4/content/docs/(root)/mcp.mdx, packages/shadcn/src/mcp/index.ts

This page is for readers who already understand the basic shadcn/ui model of adding source code to an application, but want to understand the MCP entry point. MCP, or Model Context Protocol, is the integration layer that lets clients such as Claude Code, Cursor, VS Code, Codex, and OpenCode call structured tools. The shadcn implementation exposes registry-aware tools from the CLI package and starts over standard input and output when the command is run without the initialization subcommand.

Sources: packages/shadcn/src/commands/mcp.ts, packages/shadcn/src/mcp/index.ts

Relevant Source Files

  • apps/v4/content/docs/(root)/mcp.mdx — User-facing MCP guide with the quick start, example prompts, registry configuration example, supported clients, and manual configuration notes.
  • packages/shadcn/src/mcp/index.ts — MCP server definition, tool registration, input schemas, and the registry-facing operations exposed to AI clients.
  • packages/shadcn/src/commands/mcp.ts — CLI command that starts the MCP server, loads environment files, configures stdio transport, and initializes client-specific MCP configuration files.

Core Primitives

The first primitive is the project registry map. The docs show registries configured under a registries object in components.json, such as mapping @acme to a URL pattern with a name placeholder. That configuration tells the MCP server where to resolve registry items, and the registry developer docs add that a compatible registry should expose a root registry index file. Because the server reads the project configuration, prompts such as “show me all available components” are scoped to the same registries the normal CLI would use.

Sources: apps/v4/content/docs/(root)/mcp.mdx

The second primitive is the MCP server object exported by the shadcn package. The implementation constructs a server named shadcn with version 1.0.0 and declares resource and tool capabilities. Its list-tools handler returns a catalog of callable operations with JSON schemas generated from Zod definitions. This is important for AI clients because the assistant does not need to guess arguments; it receives structured tool names, descriptions, optional filters, pagination fields, and allowed type filters from the server itself.

Sources: packages/shadcn/src/mcp/index.ts

The third primitive is the CLI command. Running the mcp command starts the server, loads environment files for the selected working directory, creates a stdio transport, and connects the exported server to that transport. Running mcp init performs client setup instead of starting a long-running conversational tool server. The same command module owns both concerns, which keeps the runtime entry point and the generated client configuration aligned around the same command, package version, and working directory behavior.

Sources: packages/shadcn/src/commands/mcp.ts

Quick Start Workflow

A typical setup begins inside the target project, not in a separate registry workspace. First confirm the project has the registry configuration it should expose to the assistant. The official quick start then asks the developer to choose an MCP client and run npx shadcn@latest mcp init with a client name. After the client is configured, restart or enable the MCP server in that client, then test with prompts that list registry components, add button, dialog, and card, or create a contact form from shadcn registry components.

Sources: apps/v4/content/docs/(root)/mcp.mdx, packages/shadcn/src/commands/mcp.ts

{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}
npx shadcn@latest mcp init --client claude
npx shadcn@latest mcp init --client cursor
npx shadcn@latest mcp init --client vscode
npx shadcn@latest mcp init --client codex
npx shadcn@latest mcp init --client opencode

The supported client list is source-backed by the CLI’s CLIENTS table. Claude Code writes an MCP server entry using .mcp.json, Cursor uses .cursor/mcp.json, VS Code uses .vscode/mcp.json, Codex is represented with a TOML server block, and OpenCode uses opencode.json with a local MCP command. Most generated configurations run npx with shadcn@latest and the mcp subcommand. VS Code uses a servers shape, while the other JSON clients use their own client-specific nesting, so copying one client’s file format to another is not reliable.

Sources: packages/shadcn/src/commands/mcp.ts

Server Tools and Registry Behavior

The visible server tool catalog starts with get_project_registries, which returns configured registry names and reports an error when components.json is missing. list_items_in_registries lists items and accepts optional registry names, item types, limit, and offset. search_items_in_registries performs fuzzy matching against item names and descriptions and uses the same registry, type, limit, and offset controls. view_items_in_registries accepts item names and returns detailed information, including file content, while the tool description directs usage-example exploration to a separate examples-oriented tool.

Sources: packages/shadcn/src/mcp/index.ts

These tools mirror the reader tasks from the docs: browse before choosing, search when the name is uncertain, inspect details before adding, and then let the assistant apply the component workflow. Pagination is exposed at the tool-schema level through limit and offset, which matters for large registries or multi-registry projects. Type filtering is constrained by the searchable type list imported from the registry search module, so a client should prefer the server-provided schema over inventing arbitrary categories. When an assistant is unsure, it should first ask the server for configured registries.

Sources: packages/shadcn/src/mcp/index.ts, apps/v4/content/docs/(root)/mcp.mdx

Configuration and Authentication Notes

The MCP page states that registries are configured in components.json, and the registry-oriented MCP docs clarify that no special server-side feature is required for a shadcn-compatible registry beyond a valid registry index. This means registry owners can usually support MCP by ensuring the normal registry contract works: a registry file is available at the expected root location, item URLs resolve from the configured pattern, and the JSON conforms to the registry schema. Consumers then add the registry namespace, such as @acme, to their project configuration.

Sources: apps/v4/content/docs/(root)/mcp.mdx

Authentication belongs to registry access rather than to a separate MCP-only component model. The CLI command loads environment files before connecting the server, which allows registry-related environment configuration to be available when tools resolve items. For protected registries, keep the project and client startup environment in mind: the assistant can only browse or install what the server process can fetch. If a client launches the command from a different directory or without the expected environment, the first troubleshooting step is to verify the working directory and components.json.

Sources: packages/shadcn/src/commands/mcp.ts, apps/v4/content/docs/(root)/mcp.mdx

Common Prompts and Next Steps

Good prompts describe both the registry scope and the desired artifact. The official examples include asking the assistant to show all available components in the shadcn registry, add button, dialog, and card, create a contact form, build a landing page with items from an acme registry, or find a login form. Those prompts work because they map to the server’s discovery and search tools before installation. When a prompt references a custom namespace, ensure that namespace exists in components.json before assuming the assistant can resolve it.

Sources: apps/v4/content/docs/(root)/mcp.mdx, packages/shadcn/src/mcp/index.ts

For deeper implementation work, read the client-integration page next if you need exact file locations and startup behavior for each MCP client. Read the registry overview and registry schema pages if you are publishing a registry and want MCP clients to discover your items reliably. Read the troubleshooting page when a client cannot find components, reports a missing components.json file, fails to start the stdio server, or behaves differently from the regular shadcn CLI. The key diagnostic question is whether the same project configuration works through both the CLI and MCP server.

Sources: apps/v4/content/docs/(root)/mcp.mdx, packages/shadcn/src/commands/mcp.ts

Ask a question...