第三方工具更新 2026.11.16

shadcn MCP 教學:Claude Code、Codex 設定與 Windows 編譯排錯

設定官方 shadcn MCP 與 Codex、Claude Code,從搜尋到安裝 Card,解決 Windows preset、TypeScript alias 與 CSS 型別錯誤。

官方 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。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

也可以在這些平台追蹤: