shadcn/uiの使い方完全ガイド - インストールからMCPサーバーまで

はじめに

ReactでモダンなUIを構築する際、コンポーネントライブラリの選択は重要な決断です。従来のUIライブラリはnpmパッケージとしてインストールし、提供されるAPIに従って使用するスタイルが一般的でした。しかし、この方式ではカスタマイズ性に制限があり、デザインシステムとの統合が難しいという課題がありました。

shadcn/uiは、この課題を根本から解決する新しいアプローチを採用しています。コンポーネントのソースコードを直接プロジェクトに配置する「Open Code」という概念により、完全なカスタマイズ性とAIとの親和性を実現しています。

本記事では、shadcn/uiのインストール方法、主要な特徴、そして2025年に注目を集めているMCPサーバーを活用したAI連携について詳しく解説します。

実行環境・前提条件

必要な環境

前提知識

• Reactの基本的なコンポーネント開発経験
• Tailwind CSSの基礎知識
• npm/pnpmなどのパッケージマネージャーの操作

対応フレームワーク

shadcn/uiは以下のフレームワークに対応しています。

• Next.js
• Vite（React）
• Remix
• Gatsby
• Astro
• Laravel

本記事ではVite + Reactを使用した手順を中心に解説します。

shadcn/uiとは

shadcn/uiは、美しくデザインされたアクセシブルなコンポーネントと、コード配布プラットフォームを組み合わせたツールです。従来のコンポーネントライブラリとは異なり、これはコンポーネントライブラリそのものではなく、「自分だけのコンポーネントライブラリを構築する方法」を提供します。

shadcn/uiの5つの特徴

1. Open Code（オープンコード）

従来のUIライブラリでは、コンポーネントの内部実装はパッケージ内に隠蔽されています。ボタンの挙動を変更したい場合、スタイルのオーバーライドやラッパーコンポーネントの作成が必要でした。

shadcn/uiでは、コンポーネントのソースコードがそのままプロジェクトに配置されます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// components/ui/button.tsx
// このファイルを直接編集してカスタマイズ可能
import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center ...",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground ...",
        destructive: "bg-destructive text-destructive-foreground ...",
        // 自由にバリアントを追加可能
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

2. Composition（コンポジション）

すべてのコンポーネントが共通の構成可能なインターフェースを持っています。異なるAPIを学ぶ必要がなく、チーム全体で予測可能な開発体験を提供します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 一貫したインターフェースでコンポーネントを組み合わせる
<Card>
  <CardHeader>
    <CardTitle>タイトル</CardTitle>
    <CardDescription>説明文</CardDescription>
  </CardHeader>
  <CardContent>
    <p>コンテンツ</p>
  </CardContent>
  <CardFooter>
    <Button>アクション</Button>
  </CardFooter>
</Card>

3. Distribution（配布システム）

shadcn/uiは、コンポーネントを配布するためのスキーマとCLIを提供します。

• スキーマ：コンポーネント、依存関係、プロパティを定義するフラットファイル構造
• CLI：クロスフレームワーク対応のコンポーネント配布・インストールツール

4. Beautiful Defaults（美しいデフォルト）

慎重に選択されたデフォルトスタイルにより、追加の作業なしで美しいUIを実現できます。すべてのコンポーネントが相互に調和するよう設計されています。

5. AI-Ready（AI対応）

オープンコードと一貫したAPIにより、AIツールとの連携が容易です。AIモデルがコンポーネントを理解し、新しいコンポーネントを生成することも可能です。

インストール手順

手順1：Viteプロジェクトの作成

まず、React + TypeScriptのプロジェクトを作成します。

1

pnpm create vite@latest my-shadcn-app

プロンプトでReactとTypeScriptを選択してください。

1
2

cd my-shadcn-app
pnpm install

手順2：Tailwind CSSの追加

shadcn/uiはTailwind CSSを使用しているため、インストールが必要です。

1

pnpm add tailwindcss @tailwindcss/vite

src/index.cssの内容をすべて以下に置き換えます。

1

@import "tailwindcss";

手順3：TypeScript設定の更新

tsconfig.jsonにbaseUrlとpathsを追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

同様にtsconfig.app.jsonにも追加します。

1
2
3
4
5
6
7
8

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

手順4：Vite設定の更新

パスエイリアスを解決するために、@types/nodeをインストールします。

1

pnpm add -D @types/node

vite.config.tsを以下のように更新します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})

手順5：shadcn/ui CLIの実行

プロジェクトにshadcn/uiを初期化します。

1

pnpm dlx shadcn@latest init

いくつかの質問に回答します。

1

Which color would you like to use as base color? › Neutral

初期化が完了すると、プロジェクトに以下のファイルが生成されます。

• components.json：shadcn/uiの設定ファイル
• src/lib/utils.ts：ユーティリティ関数
• CSSカスタムプロパティの追加

手順6：コンポーネントの追加

必要なコンポーネントを追加します。

1

pnpm dlx shadcn@latest add button

複数のコンポーネントを一度に追加することも可能です。

1

pnpm dlx shadcn@latest add button card dialog

利用可能なすべてのコンポーネントを確認するには、引数なしで実行します。

1

pnpm dlx shadcn@latest add

コンポーネントの使用

追加したコンポーネントは、以下のようにインポートして使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

import { Button } from "@/components/ui/button"

function App() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center">
      <Button>Click me</Button>
    </div>
  )
}

export default App

期待される結果

開発サーバーを起動すると、スタイリングされたボタンが画面中央に表示されます。

1

pnpm dev

主要コンポーネント一覧

shadcn/uiは60以上のコンポーネントを提供しています。以下は代表的なものです。

MCPサーバーとは

MCPの概要

MCP（Model Context Protocol）は、AIアシスタントが外部データソースやツールに安全に接続するためのオープンプロトコルです。shadcn/uiのMCPサーバーを使用することで、AIアシスタントがコンポーネントレジストリに直接アクセスできるようになります。

MCPサーバーが必要な理由

従来のshadcn/uiの使用方法では、以下の手順が必要でした。

1. 公式ドキュメントでコンポーネントを探す
2. CLIコマンドを手動で実行する
3. 使用方法を調べてコードを記述する

MCPサーバーを導入することで、これらの作業をAIアシスタントとの自然な対話で完結できます。

1
2
3
4

「ログインフォームを作成して」
→ AIが必要なコンポーネントを特定
→ 自動的にインストール
→ フォームのコードを生成

MCPサーバーの機能

shadcn MCPサーバーは以下の機能を提供します。

• コンポーネントの閲覧：利用可能なコンポーネント、ブロック、テンプレートの一覧表示
• レジストリ横断検索：複数のソースから特定のコンポーネントを検索
• 自然言語でのインストール：「ログインフォームを追加して」のような会話形式でコンポーネントを追加
• 複数レジストリのサポート：公開レジストリ、プライベートライブラリ、サードパーティソースへのアクセス

MCPサーバーの設定方法

VS Code（GitHub Copilot）での設定

プロジェクトの.vscode/mcp.jsonを作成し、以下の内容を記述します。

1
2
3
4
5
6
7
8

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

設定後、.vscode/mcp.jsonを開き、shadcnサーバーの横にある「Start」をクリックします。

Cursorでの設定

.cursor/mcp.jsonを作成します。

1
2
3
4
5
6
7
8

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

設定後、Cursor SettingsでMCPサーバーを有効化します。

Claude Codeでの設定

CLIで自動設定が可能です。

1

pnpm dlx shadcn@latest mcp init --client claude

または、.mcp.jsonを手動で作成します。

1
2
3
4
5
6
7
8

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

Claude Codeを再起動し、/mcpコマンドで接続状態を確認できます。

MCPサーバーの活用例

MCPサーバーを設定すると、AIアシスタントに以下のようなプロンプトで指示できます。

コンポーネントの閲覧と検索

1

shadcnレジストリで利用可能なすべてのコンポーネントを表示して

1

shadcnレジストリからログインフォームを探して

コンポーネントのインストール

1

buttonコンポーネントをプロジェクトに追加して

1

shadcnコンポーネントを使ってログインフォームを作成して

複数レジストリの活用

components.jsonで追加のレジストリを設定できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

設定後、以下のようにプロンプトできます。

1
2

acmeレジストリのhero、features、testimonialsセクションを使って
ランディングページを作成して

トラブルシューティング

MCPサーバーが応答しない場合

1. 設定ファイルが正しいか確認
2. MCPクライアントを再起動
3. shadcnがプロジェクトにインストールされているか確認
4. レジストリへのネットワーク接続を確認

「No tools or prompts」エラーが表示される場合

1. npxキャッシュをクリア

   1	npx clear-npx-cache

2. MCPサーバーを再有効化
3. Cursorの場合、View → Outputで「MCP: project-*」のログを確認

まとめ

shadcn/uiは、従来のコンポーネントライブラリの課題を解決する革新的なアプローチを提供しています。Open Codeにより完全なカスタマイズ性を実現し、MCPサーバーによってAIアシスタントとのシームレスな連携が可能になりました。

本記事で解説した内容を活用することで、以下のことが実現できます。

• 美しくアクセシブルなUIの迅速な構築
• プロジェクト固有の要件に合わせたコンポーネントのカスタマイズ
• AIアシスタントを活用した効率的な開発ワークフロー

2025年のReact開発において、shadcn/uiはUIコンポーネント構築の標準的な選択肢の一つとなっています。ぜひプロジェクトに導入して、その開発体験を実感してください。

参考リンク

• shadcn/ui 公式ドキュメント
• shadcn/ui インストールガイド（Vite）
• shadcn/ui MCPサーバードキュメント
• shadcn/ui GitHub リポジトリ
• Model Context Protocol 公式サイト
• Radix UI 公式サイト
• Tailwind CSS 公式ドキュメント