Third-party toolUpdated 2026.11.16

shadcn MCP Setup: Claude Code, Codex and Windows Build Fixes

Connect official shadcn MCP to Codex and Claude Code, install Card in a Vite app, and fix Windows preset, TypeScript alias and CSS declaration errors.

Aaron recommends Open official GitHub

The official shadcn MCP server lets your coding assistant search component registries and work from their actual entries. Use it when you want the agent to find a component, read an example and install the right source into an existing React project. If you already know you need Card, the ordinary shadcn CLI is enough. This guide connects the official server and follows a Card through to a passing TypeScript check and Vite build on Windows.

Pick the official server first

This guide uses shadcn 4.23.0, maintained in shadcn-ui/ui. It runs locally through Node and stdio. Products with similar names can have different registries, HTTP endpoints and subscription requirements; use the official MCP documentation as your reference for this server.

Prepare your project

Start inside an existing Vite + React + TypeScript + Tailwind 4 application. If you need that application setup first, follow the official Vite guide. Use a current Node 24 runtime for this walkthrough; the shadcn package itself declares a minimum of Node 20.18.1, but your build tools can require more.

Your app needs an @ alias pointing at src, in both the TypeScript config that includes your source and the Vite config. For TypeScript 7, the relevant TypeScript entry is:

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

Merge that entry into the existing config; keep its other compiler options and source includes. For Vite, align the alias with the same directory while preserving the application's plugins:

import { fileURLToPath } from "node:url"
// Inside defineConfig({...}):
// resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }

Install the pinned CLI and initialize the application:

npm install --save-dev shadcn@4.23.0
npx shadcn --version
npx shadcn init --template vite --preset nova --base radix --yes --no-monorepo --no-rtl --no-reinstall
npx shadcn info

Expect version 4.23.0, a generated components.json, and project information showing your aliases and CSS file. Review the initialization changes before continuing. In this layout the generated CSS file is src/index.css; the file path is recorded in components.json.

Connect Codex or Claude Code

On Windows, a project-local node entry avoids relying on an MCP host to resolve npx. First locate the installed server:

node --version
Resolve-Path ./node_modules/shadcn/dist/index.js

Codex

Merge this table into ~/.codex/config.toml. Replace C:/work/invoice-ui in both places with your actual project folder; forward slashes keep the Windows paths readable in TOML.

[mcp_servers.shadcn]
command = "node"
args = ["C:/work/invoice-ui/node_modules/shadcn/dist/index.js", "mcp"]
cwd = "C:/work/invoice-ui"

Restart Codex, run codex mcp list, and start a session in that application. The list confirms configuration; asking the agent to search the registry is the next check that it can actually use the tools. The shadcn initializer does not automatically write Codex's TOML; see the Codex MCP reference.

Claude Code

Run these commands in the application folder:

$server = (Resolve-Path ./node_modules/shadcn/dist/index.js).Path
claude mcp add --scope project --transport stdio shadcn -- node $server mcp
claude mcp list

The project entry should report Connected. Restart an open Claude Code session and use /mcp to inspect it. The --scope project setting writes the project's .mcp.json, so review and merge any existing entry rather than creating a second server with the same name. More options are in the Claude Code MCP guide.

For Cursor, use the official Cursor configuration section.

Three practical tasks

1. Find Card, install it and compile

Paste this into Codex after connecting:

Use the shadcn MCP server to search @shadcn for card, inspect @shadcn/card, and get its add command. Use the locally installed 4.23.0 CLI to install it. Show the generated file, then run TypeScript checking and the Vite build.

The tools we used were search_items_in_registries, view_items_in_registries and get_add_command_for_items. The last tool returned a command using shadcn@latest; for this project, execute the already installed version instead:

npx shadcn add @shadcn/card --yes

In the demonstrated layout it creates src/components/ui/card.tsx. Import it into a component that your existing entry point renders:

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function InvoiceSummary() {
  const invoices = [
    { amount: 120, status: "paid" },
    { amount: 80, status: "paid" },
    { amount: 50, status: "open" },
  ]
  const paid = invoices.filter(invoice => invoice.status === "paid")
  const total = paid.reduce((sum, invoice) => sum + invoice.amount, 0)
  return (
    <Card>
      <CardHeader><CardTitle>Invoice summary</CardTitle></CardHeader>
      <CardContent>Paid total: {total}</CardContent>
    </Card>
  )
}
npx tsc --noEmit
npm run build

Both should finish with exit 0. The data expression totals 200, excluding the open invoice. Compilation checks imports and types; inspect the rendered page separately before shipping a UI change.

2. Read a usage example instead of guessing the API

Use get_item_examples_from_registries to retrieve card-demo from @shadcn. Show how CardHeader, CardTitle, CardContent and CardFooter are composed. Compare that example with InvoiceSummary before editing it.

Expect a usage example with code and dependencies. In 4.23.0, our view_items_in_registries call returned metadata such as item type, file count and dependencies. It did not return the component's full implementation. Use the examples tool for composition, or inspect the installed card.tsx when implementation details matter.

3. Audit what the installation changed

Use get_audit_checklist from the shadcn MCP server. Apply its import, dependency and TypeScript checks to the generated Card and InvoiceSummary. Run tsc --noEmit and the Vite build, and report any failure before proposing more components.

The tool supplies an audit checklist; the coding assistant still has to inspect files and execute the checks. This catches the gap between “the registry found it” and “it works in this application.” Check components.json if the installed location differs from the example.

Windows errors we encountered

Invalid preset: base-nova

The 4.23.0 help text's defaults led us to try base-nova, which the command rejected. The actual available list included nova, so initialization succeeded with --preset nova --base radix. Use the explicit command above instead of copying that default label as a preset name.

TS5102 and TS5090 after alias configuration

Our TypeScript 7.0.2 reported Option 'baseUrl' has been removed and Non-relative paths are not allowed. Remove baseUrl for that compiler and use "paths":{"@/*":["./src/*"]}. The leading ./ matters. Apply the setting to the config containing your application sources, and keep Vite's alias aligned; an older TypeScript project can have different requirements.

TS2882 for ./index.css

TypeScript then reported Cannot find module or type declarations for side-effect import of './index.css'. We added src/vite-env.d.ts with:

/// <reference types="vite/client" />

That supplies Vite's client declarations. The native TypeScript check and Vite build both passed afterwards, without suppressing the error or weakening strict.

The server connects but the agent cannot find components

Check the application directory and its components.json. In a monorepo, point cwd at the actual application, not merely the repository root. A stdio server waiting quietly is normal; it needs a client to send protocol messages. For a missing registry item, verify the namespace and name, such as @shadcn/card.

Cost, limits and alternatives

The official CLI is MIT-licensed, and the public registry used here needs no registry account. Your AI client and third-party registries have their own access and pricing. Adding a component copies source into your application; you own the resulting modifications and must review future updates.

MCP supplies registry discovery and tools, not a finished design or proof of accessibility. The add-command tool returns a command; a client must execute it to write files. If you already know the component name, npx shadcn add is the shorter path.

Use Context7 for general library documentation rather than registry items. Use Playwright MCP when you need to check the rendered page and interactions after the build passes.

FAQ

How do I install shadcn MCP for Codex?

Install shadcn in the application and add the server table to ~/.codex/config.toml, then restart Codex. Keep the server's working directory on the application containing components.json. Confirm it with a real registry search, not only codex mcp list.

How do I connect shadcn MCP to Claude Code?

Use claude mcp add --scope project --transport stdio with the local server command shown above. claude mcp list should report Connected, and a restarted session exposes it through /mcp. Configure the React application's styling and aliases separately from the MCP connection.

Does shadcn MCP install components automatically?

In our tested toolset, get_add_command_for_items returned an installation command. The coding agent then executed the CLI to create the component file. Review the changed source and run the project checks before treating installation as complete.

Does the official shadcn MCP require a paid plan?

The local official server and the public registry route used here do not require a registry subscription. Other services with similar names can use paid HTTP endpoints and different component collections. Check which package or endpoint your configuration actually starts.

What we tested

On November 16, 2026, Windows Codex used shadcn 4.23.0 for five successful MCP calls, live public-registry examples, initialization and Card installation. The native app passed TypeScript 7.0.2 and Vite 8.3.8 after the preset, alias and CSS-declaration fixes. Claude Code add/list reported Connected. The team also replayed the CLI/build path independently. Cursor, private registries, Claude model tasks, browser appearance and accessibility were not tested. Official MCP, client and Vite setup references were checked on the same date.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Or follow us on: