官方 shadcn MCP 讓 AI 程式工具查詢元件 registry、讀用法,再把正確元件來源裝進現有 React 專案。適合常請 AI 找元件、組合介面的開發者;如果早就知道只要 Card,直接用 CLI 更快。這篇從接上伺服器走到 Card 落地、TypeScript 檢查與 Vite 建置,並整理 Windows 真正遇到的錯誤。
先確認你要裝哪一個 shadcn MCP
本篇使用 shadcn-ui/ui維護的 shadcn 4.23.0,由本機 Node 透過 stdio 啟動。同名或近似名稱的服務可能使用其他 registry、HTTP 網址與付費方案;這個伺服器請以官方 MCP 文件為準。
準備既有專案
以下從已能運作的 Vite+React+TypeScript+Tailwind 4 專案開始。尚未有專案,先依官方 Vite 安裝文件完成環境。這條路線建議使用目前的 Node 24;shadcn 套件本身最低要求 Node 20.18.1,但建置工具可能要求更高版本。
應用程式需要把 @ 對應到 src,而且 TypeScript 與 Vite 要指向相同目錄。使用 TypeScript 7 時,相關設定為:
{
"compilerOptions": {
"paths": { "@/*": ["./src/*"] }
}
}
把這個欄位合併到包含應用程式原始碼的 TypeScript 設定,保留其他編譯選項與 include。Vite 端也要對齊 alias,並保留專案原有的 plugins:
import { fileURLToPath } from "node:url"
// Inside defineConfig({...}):
// resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }
在專案目錄安裝固定版本並初始化:
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
應顯示 4.23.0,產生 components.json,並能在 info 看見專案的 CSS 與 alias。繼續前先檢查初始化改了哪些檔案。本例使用 src/index.css;實際位置記在 components.json。
接上 Codex 或 Claude Code
Windows 可以直接以 node 啟動專案內已安裝的伺服器,減少 MCP host 找不到 npx 的問題。先確認路徑:
node --version
Resolve-Path ./node_modules/shadcn/dist/index.js
Codex
把下列設定合併到 ~/.codex/config.toml。兩處 C:/work/invoice-ui 都換成真正的專案目錄;TOML 路徑使用 / 可減少 Windows 反斜線跳脫問題。
[mcp_servers.shadcn]
command = "node"
args = ["C:/work/invoice-ui/node_modules/shadcn/dist/index.js", "mcp"]
cwd = "C:/work/invoice-ui"
重啟 Codex,執行 codex mcp list,再從這個應用程式開啟工作階段。清單只確認設定存在,下一步要請它真正搜尋 registry。shadcn 初始化工具不會自動替 Codex 寫好 TOML;其他選項見 Codex MCP 文件。
Claude Code
在應用程式目錄執行:
$server = (Resolve-Path ./node_modules/shadcn/dist/index.js).Path
claude mcp add --scope project --transport stdio shadcn -- node $server mcp
claude mcp list
預期顯示 Connected。已開啟的 Claude Code 工作階段要重啟,再以 /mcp 檢查工具。--scope project 寫入專案的 .mcp.json;若原本已有同名 server,先檢查合併,不要重複註冊。更多設定見 Claude Code MCP 文件。
Cursor 的接法請見官方 Cursor 設定段落。
三個實際用途
1. 找到 Card、裝進專案並編譯
在接好伺服器的 Codex 貼上:
使用 shadcn MCP 搜尋 @shadcn 的 card,查看 @shadcn/card,取得安裝命令。用專案已安裝的 4.23.0 CLI 執行安裝,列出產生的檔案,再跑 TypeScript 檢查與 Vite build。
我們實際使用 search_items_in_registries、view_items_in_registries、get_add_command_for_items。最後一個工具回傳含 shadcn@latest 的命令;要重現此版本,改用專案內已安裝的 CLI:
npx shadcn add @shadcn/card --yes
本例會建立 src/components/ui/card.tsx。在現有入口會渲染的元件中匯入:
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
兩者應以退出碼 0 結束。這段資料運算得到 200,排除未付款的50。編譯核對匯入與型別;正式使用介面前,仍要另外查看實際渲染結果。
2. 先讀用法範例,避免猜元件 API
使用 get_item_examples_from_registries 取得 @shadcn 的 card-demo。說明 CardHeader、CardTitle、CardContent、CardFooter 怎麼組合,先與 InvoiceSummary 比較,再決定是否修改。
應取得範例程式與相依元件。4.23.0 的 view_items_in_registries 在我們的呼叫中回傳類型、檔案數與依賴等 metadata,沒有直接包含完整實作。要看組合方式用 examples 工具;要查實作,直接讀已安裝的 card.tsx。
3. 安裝後核對變更
使用 shadcn MCP 的 get_audit_checklist。依清單檢查新 Card 與 InvoiceSummary 的匯入、依賴和 TypeScript,再跑 tsc --noEmit 與 Vite build;先回報任何失敗,不要繼續加更多元件。
這個工具提供核對清單,AI 還是要真的讀檔與執行命令。它幫你檢查「registry 找得到」到「目前專案能用」中間的落差。元件出現在不同路徑時,先看 components.json 的 alias。
Windows 實際遇到的錯誤
Invalid preset: base-nova
4.23.0 help 的預設說明讓我們先試了 base-nova,實際命令卻拒絕這個名稱。錯誤列出的有效選項包含 nova,改用 --preset nova --base radix 後初始化成功。重現時可直接用上面的明確命令。
TS5102、TS5090:baseUrl 與相對路徑
使用 TypeScript 7.0.2 時,我們看到 Option 'baseUrl' has been removed 與 Non-relative paths are not allowed。在該版本移除 baseUrl,改用 "paths":{"@/*":["./src/*"]},注意開頭的 ./。修改包含應用程式來源的設定檔,並讓 Vite alias 指向同一目錄;較舊 TypeScript 的設定方式可能不同。
TS2882:找不到 ./index.css 的型別
接著 TypeScript 回報 Cannot find module or type declarations for side-effect import of './index.css'。我們加入 src/vite-env.d.ts:
/// <reference types="vite/client" />
這會帶入 Vite 的 client 型別宣告。加入後,Windows 原生 TypeScript 與 Vite 建置都通過,不需要關閉 strict 或壓掉錯誤。
連線成功,卻找不到專案元件
確認 cwd 指向應用程式,且該目錄有 components.json。Monorepo 要選真正的 app,不一定是 repo 根目錄。stdio server 在終端機安靜等待是正常行為,需要客戶端送進協定訊息。特定元件找不到時,檢查 namespace 與名稱,例如 @shadcn/card。
費用、限制與替代選擇
官方 CLI 採 MIT 授權,這裡使用的公開 registry 不需要 registry 帳號。AI 客戶端與第三方 registry 各有自己的存取與計費方式。安裝會把元件原始碼複製進專案,後續自訂與更新要自行檢查。
MCP 提供查詢工具,不會直接給你完成的設計,也不代表通過無障礙檢查。Add-command 工具回傳命令,客戶端仍須執行 CLI 才會寫出檔案。已知元件名稱時,直接 npx shadcn add 就是更短的路徑。
需要一般函式庫文件時用 Context7;建置通過後要查實際畫面與互動,可用 Playwright MCP。
FAQ
shadcn MCP 怎麼接 Codex?
先在 app 安裝 shadcn,將 server table 加到 ~/.codex/config.toml,再重啟 Codex。工作目錄要指向含 components.json 的應用程式。除了看清單,也要真正搜尋一次 registry 才能確認工具可用。
Claude Code 如何安裝 shadcn MCP?
在專案執行上面的 claude mcp add --scope project --transport stdio,指定本機伺服器命令。以 claude mcp list 確認 Connected,再重啟工作階段查看 /mcp。React 專案的樣式與 alias 仍要另外完成。
shadcn MCP 會自動把元件裝進去嗎?
我們測到的 get_add_command_for_items 回傳安裝命令,接著由 AI 執行 CLI 產生檔案。找到元件不等於完成安裝。應查看產生的來源並跑專案檢查,再繼續修改介面。
官方 shadcn MCP 要付費嗎?
本機官方 server 與本文公開 registry 路線不需要 registry 訂閱。相近名稱的其他服務可能使用付費 HTTP 端點與不同元件庫。先確認設定實際啟動哪個套件或網址,才不會把別家服務的限制套到這裡。
我們測了什麼
團隊於 2026-11-16 在 Windows Codex 使用 shadcn 4.23.0,完成五個 MCP 呼叫、即時公開 registry 範例、初始化與 Card 安裝。 修正 preset、alias 與 CSS 宣告後,原生 TypeScript 7.0.2、Vite 8.3.8 通過;Claude Code add/list 顯示 Connected。 另獨立重跑 CLI 與編譯;未測 Cursor、私人 registry、Claude 模型任務、瀏覽器外觀與無障礙。 官方 MCP、客戶端與 Vite 設定文件查閱日為 2026-11-16。