Claude Media
Claude Codeでshadcn MCPを使いUI部品を追加させる手順
Claude CodeMCPチュートリアル

Claude Codeでshadcn MCPを使いUI部品を追加させる手順

shadcn MCPサーバーをClaude Codeに接続し、レジストリの検索とコンポーネント追加を自然文で頼む手順を解説します。.mcp.jsonの書き方、承認の流れ、プライベートレジストリの認証まで扱います。

読了目安 約13分

shadcn MCPサーバーを繋ぐと、Claude Codeに「buttonとdialogとcardを追加して」と頼むだけで、shadcn/uiのレジストリから部品を探してプロジェクトに入れてくれます。接続は1コマンドです。ただし、設定ファイルの置き場所とClaude Code側の承認を押さえておかないと、繋いだつもりで動いていない状態になります。

shadcn MCPサーバーは、AIアシスタントとコンポーネントのレジストリ、shadcn CLIをつなぐ橋渡し役です。レジストリはcomponents.jsonに書いた配布元の一覧で、標準のshadcn/uiレジストリは設定なしで使えます。

1コマンドで接続する

プロジェクトのルートで次を実行します。

pnpm dlx shadcn@latest mcp init --client claude

pnpmのほか、npm・yarn・bunのコマンドも用意されています。実行後にClaude Codeを再起動すると、次のような依頼が通ります。

  • shadcnレジストリで使えるコンポーネントを一覧にして
  • buttonとdialogとcardをプロジェクトに追加して
  • shadcnのコンポーネントでお問い合わせフォームを作って

つながっているかどうかは、Claude Code上で/mcpを実行して確かめます。一覧にshadcnが出てConnectedと表示されれば準備完了です。

手動で.mcp.jsonに書く

initを使わず自分で設定するときは、プロジェクトの.mcp.jsonに次を書きます。

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

stdio型のサーバーなので、claude mcp addでも同じ登録ができます。--より後ろがサーバーの起動コマンドです。

claude mcp add --transport stdio shadcn \
  --scope project -- npx shadcn@latest mcp

--scope projectを付けると、プロジェクト直下の.mcp.jsonに書き込まれます。チームで同じ設定を使うなら、このファイルをコミットします。

承認が済むまでは動かない

プロジェクトスコープのサーバーは、Claude Codeが対話セッションで承認を求めます。承認前はclaude mcp listにPending approvalと出て、接続も確認もされません。claudeを対話モードで起動して承認すれば解消します。

cloneしたばかりのリポジトリでは、さらに一段あります。ワークスペースを信頼するダイアログに応じるまで、リポジトリにコミットされた.claude/settings.jsonの承認設定は無視されます。他人が置いた.mcp.jsonを黙って有効にできないための仕組みです。

頼み方の型

shadcn側のドキュメントには、用途別の依頼例が載っています。

目的依頼の例
探す依頼の例shadcnレジストリのログインフォームを探して
入れる依頼の例buttonコンポーネントをプロジェクトに追加して
組み立てる依頼の例shadcnのコンポーネントでログインフォームを作って
別レジストリを使う依頼の例acmeレジストリのコンポーネントを見せて

依頼文にレジストリ名を入れるのがコツです。「acmeレジストリのhero、features、testimonialsを使ってランディングページを作って」のように、配布元を指定すると部品の取り違えが減ります。

完了条件をCLAUDE.mdに書いておく

追加した部品が本当にビルドを通るかは、MCPサーバーでは保証されません。確認の手順をCLAUDE.mdに書いておくと、毎回の依頼文が短くなります。次は、そのまま使える書き方の一例です。

## UIコンポーネントの追加ルール
- shadcn/uiの部品はshadcn MCPのレジストリから追加し、手書きで複製しない
- 追加後は`pnpm typecheck`と`pnpm lint`を実行し、エラーが出たら修正してから報告する
- 追加したファイルの一覧を最後に示す

追加の度に型チェックを走らせる運用にすれば、依存の不足や配置先のずれを、依頼の直後に拾えます。

追加前に差分を見たいとき

MCPサーバーの裏側で動くのはshadcn CLIです。部品を入れる前に中身や変更内容を見たいなら、同じ操作をCLIで直接実行できます。依頼文に「まず--dry-runで確認して」と添える使い方もあります。

コマンドできること
shadcn search @shadcn -q "button"できることレジストリから部品を検索する(listは別名)
shadcn view button card dialogできること入れる前に部品の中身を見る
shadcn add button --dry-runできることファイルを書かずに変更内容を見る
shadcn add button --diffできること既存ファイルとの差分を表示する
shadcn add button --overwriteできること既存のファイルを上書きする

searchの表示件数は、レジストリごとに既定で100件までです。--limitと--offsetで範囲を動かせます。addには--pathもあり、配置先のディレクトリを指定できます。

プロジェクトの設定を調べるshadcn infoと、コンポーネントのドキュメントやAPI参照を取ってくるshadcn docs buttonもあります。どちらも--jsonを付けるとJSONで出力されるので、Claude Codeに結果を読ませて「この構成に合う使い方を教えて」と続ける依頼がしやすくなります。

すでに手を入れたコンポーネントがあるプロジェクトでは、--overwriteを付けた追加が自分の変更を消します。Claude Codeに「buttonを追加して」と頼んで既存のbuttonと衝突しそうなときは、先に--diffで差分を出させると、上書きの影響を見てから判断できます。

レジストリを増やす

サードパーティやプライベートのレジストリは、components.jsonのregistriesに@名前空間付きで足します。

{
  "registries": {
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": {
      "url": "https://internal.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

名前空間は@で始まり、英数字・ハイフン・アンダースコアだけで構成します。参照は@namespace/resource-nameの形です。Claude Codeには「@internal/auth-formを入れて」と指定できます。

認証が要るレジストリは、トークンを.env.localに置きます。

REGISTRY_TOKEN=your_token_here

headersの値にある${REGISTRY_TOKEN}は、この環境変数に置き換わります。トークンをcomponents.jsonへ直接書かないでください。このファイルはふつうコミットされます。

認証の書き方は3通りある

トークンを渡す場所は、レジストリ側の仕様に合わせて選びます。

  • Bearerトークン: headersに"Authorization": "Bearer ${REGISTRY_TOKEN}"を書く。上の例がこの形です
  • APIキー: headersに"X-API-Key": "${API_KEY}"のようなヘッダーを置く。X-Workspace-Idなど複数のヘッダーも並べられます
  • クエリパラメーター: paramsに"token": "${ACCESS_TOKEN}"と書くと、https://registry.company.com/button.json?token=…の形でリクエストされる

クエリパラメーターは設定が短く済む反面、URLにトークンが載ります。サーバーのアクセスログにも残るので、ヘッダー方式が選べるならヘッダーを使うほうが無難です。

GitHubのアドレスと名前空間の使い分け

公開のGitHubリポジトリにあるレジストリなら、名前空間を設定しなくてもshadcn add acme/ui/buttonの形で入れられます。components.jsonを書き換えずに済むのが利点です。認証、リクエストヘッダー、クエリパラメーター、プライベートレジストリが要るときは、@acme/buttonのような名前空間を使います。

自社でレジストリを配るなら、registry.jsonを書いてshadcn buildを実行します。public/rにレジストリのJSONが生成され、出力先は--outputで変えられます。生成したJSONを社内で配信すれば、前の節の@internalがそのまま指す先になります。

つながらないときの切り分け

接続の失敗は、原因が3か所に分かれます。

切り分け

症状ごとの確認先

  • 応答がない

    MCPクライアントで有効になっているかを確認し、設定変更のあとにClaude Codeを再起動します。プロジェクトにshadcnが入っていること、レジストリにネットワークから届くことも条件です。

  • レジストリから取れない

    components.jsonのURLと、@namespace/componentの書き方を見ます。プライベートレジストリなら環境変数が設定されているかも確認します。

  • 追加に失敗する

    components.jsonが有効か、配置先のディレクトリがあるか、書き込み権限があるかを見ます。必要な依存が入っていることも条件です。

「No tools or prompts」と表示されたときは、npx clear-npx-cacheでnpxのキャッシュを消してから、サーバーを再度有効にします。接続が一部だけ落ちたときは、失敗したMCPサーバーを一括で再接続する方法も使えます。

接続状態は、Claude Code側のコマンドでも見られます。

claude mcp list
claude mcp get shadcn

claude mcp listは各サーバーの状態を✔ Connected、! Needs authentication、✘ Failed to connectのように示します。承認の選択をやり直したいときはclaude mcp reset-project-choicesを実行します。

一覧が長いときの出力上限

「使えるコンポーネントを全部一覧にして」のような依頼は、MCPツールの出力が長くなります。Claude Codeは1回のツール出力が10,000トークンを超えると警告を出し、既定では25,000トークンで打ち切ります。上限はMAX_MCP_OUTPUT_TOKENSで変えられます。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

警告のしきい値は固定です。また、成功した結果が5万文字を超えると、この変数に関係なくファイルに保存されます。上限を上げるより、「formに関係する部品だけ」と範囲を絞って頼むほうが、あとの処理も軽く済みます。

スコープの優先順位

同じ名前のサーバーが複数の場所に定義されているとき、Claude Codeは一番優先度が高い定義を1つだけ使って接続します。優先順位は次のとおりです。

  1. ローカルスコープ
  2. プロジェクトスコープ
  3. ユーザースコープ
  4. プラグインが提供するサーバー
  5. claude.aiのコネクタ

重複は、ローカル・プロジェクト・ユーザーの3つについては名前で判定します。採用された定義のエントリが丸ごと使われ、スコープをまたいだフィールドの統合はありません。たとえばユーザースコープのshadcnに環境変数を足してあっても、プロジェクトの.mcp.jsonに同名のエントリがあれば、そちらだけが効きます。

ほかのMCPサーバーとの組み合わせ方

shadcn MCPは、UI部品の取得に特化したサーバーです。Claude Codeの追加手順とスコープの考え方はClaude Code MCP設定ガイドで扱っています。最初に繋ぐ1本を迷うときは、おすすめMCPサーバー10選で用途別の選び方を確認できます。

スコープをプロジェクトにそろえておくと、部品追加の依頼がチームの誰のセッションでも同じ前提で動きます。ユーザースコープにもshadcnを登録していた場合は、前節の優先順位でプロジェクト側の定義が選ばれ、ユーザー側の定義は使われません。個人用の設定を足したつもりで反映されない原因はここにあります。二重登録は、ユーザー側をclaude mcp removeで消して、プロジェクト側に一本化するのが扱いやすい構成です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →