Civitai MCP Server

🚀 Civitai MCP Server

このサーバーは、Model Context Protocol (MCP) を利用して、AIアシスタントからCivitaiのAIモデル、クリエイター、生成コンテンツにアクセスできるようにします。MCPに対応したAIアシスタントを通じて、AIモデルの閲覧、検索、発見をシームレスに行うことができます。

✨ 主な機能

🔍 モデルの発見

• 高度な検索：タイプ、クリエイター、タグなどを使った柔軟なフィルタリングでAIモデルを検索できます。
• カテゴリ別閲覧：タイプ（チェックポイント、LoRA、ControlNetなど）別にモデルを探索できます。
• 人気とトレンド：最もダウンロードされている、評価の高いモデルを発見できます。
• 最新モデル：新しくアップロードされたモデルを追跡できます。
• ハッシュ検索：ファイルのハッシュ値でモデルを検索し、検証できます。

👨‍💻 クリエイターとコミュニティ

• クリエイタープロフィール：モデルのクリエイターを閲覧、検索できます。
• クリエイターコレクション：特定のクリエイターのすべてのモデルを表示できます。
• タグシステム：Civitaiの包括的なタグシステムを通じてモデルを探索できます。

🖼️ 生成コンテンツ

• 画像ギャラリー：詳細なメタデータ付きのAI生成画像を閲覧できます。
• 生成パラメータ：プロンプト、設定、モデル情報にアクセスできます。
• コミュニティショーケース：コミュニティの素敵な作品を発見できます。

📊 モデルインテリジェンス

• 詳細なモデル情報：完全なモデル仕様、バージョン、ファイル情報を取得できます。
• バージョン履歴：モデルの更新と改善を追跡できます。
• ダウンロードURL：認証をサポートしたモデルのダウンロードURLに直接アクセスできます。
• コンテンツセーフティ：ピクルスキャンとウイルスセーフティの結果にアクセスできます。

📦 インストール

前提条件

• Node.js 18+
• npmまたはyarn
• Civitai APIキー（任意ですが、高いレート制限を利用する場合は推奨）

クイックスタート

1. リポジトリをクローンします：

git clone https://github.com/Cicatriiz/civitai-mcp-server.git
cd civitai-mcp-server

2. 依存関係をインストールします：

npm install

3. サーバーをビルドします：

npm run build

4. APIキーを設定します（任意）：

export CIVITAI_API_KEY="your_api_key_here"

5. サーバーを起動します：

npm start

Civitai APIキーの取得方法

1. Civitai API Keysにアクセスします。
2. Civitaiアカウントにログインします。
3. 新しいAPIキーを生成します。
4. キーをコピーし、環境変数として設定します。

💻 使用例

基本的なモデル検索

アニメ関連のSDXL LoRAモデルを検索します：
- ツール: search_models
- クエリ: "anime"
- タイプ: ["LORA"]
- ベースモデル: ["SDXL 1.0"]

人気モデルの取得

今週最もダウンロードされたモデルを取得します：
- ツール: get_popular_models
- 期間: "Week"
- 制限: 10

モデルの詳細情報取得

特定のモデルの詳細情報を取得します：
- ツール: get_model
- モデルID: 12345

生成画像の閲覧

最近のAI生成画像を探索します：
- ツール: browse_images
- ソート: "Newest"
- 制限: 50
- NSFW: "None"

📚 ドキュメント

利用可能なツール

APIリファレンス

モデルタイプ

• Checkpoint - 完全なStable Diffusionモデル
• LORA - 低ランク適応モデル
• TextualInversion - テキスト埋め込みモデル
• Hypernetwork - ハイパーネットワークモデル
• ControlNet - ControlNetモデル
• AestheticGradient - 審美勾配モデル
• Poses - ポーズモデル

ソートオプション

• Highest Rated - コミュニティからの最高評価
• Most Downloaded - 最もダウンロードされている
• Newest - 最近アップロードされた

期間

• AllTime - 時間制限なし
• Year - 過去12ヶ月
• Month - 過去30日
• Week - 過去7日
• Day - 過去24時間

APIカバレッジ

このMCPサーバーは、Civitai API v1のすべての主要エンドポイントを実装しています：

• ✅ /api/v1/models - モデルの一覧と検索
• ✅ /api/v1/models/:id - 特定のモデルを取得
• ✅ /api/v1/model-versions/:id - モデルのバージョンを取得
• ✅ /api/v1/model-versions/by-hash/:hash - ハッシュ値でモデルを取得
• ✅ /api/v1/images - 画像を閲覧
• ✅ /api/v1/creators - クリエイターの一覧を取得
• ✅ /api/v1/tags - モデルのタグを閲覧
• ✅ 認証をサポートしたモデルのダウンロードURL

サポートされるモデルタイプ

• Checkpoint - 完全なStable Diffusionモデル
• LORA - 低ランク適応モデル
• TextualInversion - テキスト埋め込みモデル
• Hypernetwork - ハイパーネットワークモデル
• AestheticGradient - 審美勾配モデル
• Controlnet - ControlNetモデル
• Poses - ポーズモデル

コンテンツフィルタリング

サーバーはCivitaiのコンテンツフィルタリングシステムをサポートしています：

• NSFWコンテンツレベル（None, Soft, Mature, X）
• 商用利用許可
• モデルのライセンスオプション

エラーハンドリング

サーバーは以下のエラーを包括的にハンドリングします：

• APIレート制限
• ネットワーク接続問題
• 無効なパラメータ
• 認証エラー
• データ検証エラー

開発

プロジェクト構造

civitai-mcp-server/
├── src/
│   ├── index.ts          # メインサーバーの実装
│   ├── civitai-client.ts # Civitai APIクライアント
│   └── types.ts          # TypeScriptの型定義
├── dist/                 # コンパイルされたJavaScript出力
├── tests/                # テストファイル
└── docs/                 # 追加のドキュメント

ソースからのビルド

# 依存関係をインストールします
npm install

# TypeScriptをビルドします
npm run build

# テストを実行します
npm test

# ホットリロードで開発モードを起動します
npm run dev

テスト

# 包括的なテストスイートを実行します
npm test

# 特定のエンドポイントをテストします
node test.js
node comprehensive-test.js

コントリビューション

コントリビューションを歓迎します！詳細はContributing Guideを参照してください。

開発セットアップ

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新機能に対するテストを追加します。
5. プルリクエストを送信します。

制限事項

• レート制限：Civitai APIにはレート制限があります。APIキーを使用すると、より高い制限が利用できます。
• NSFWコンテンツ：アカウント設定に基づいて、一部のコンテンツがフィルタリングされる場合があります。
• モデルの可用性：一部のモデルは一時的に利用できない場合や、認証が必要な場合があります。

トラブルシューティング

一般的な問題

サーバーが起動しない場合：

• Node.js 18+がインストールされていることを確認してください。
• すべての依存関係がインストールされていることを確認してください（npm install）。
• ビルドが正常に完了したことを確認してください（npm run build）。

APIレート制限の問題：

• Civitai APIキーを取得し、CIVITAI_API_KEY環境変数を設定してください。
• 制限に達した場合は、リクエスト頻度を減らしてください。

モデルが見つからない場合：

• モデルIDの正確性を確認してください。
• モデルが削除されたり、非公開になっていないことを確認してください。
• 検索クエリのスペルが正しいことを確認してください。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

関連プロジェクト

• Model Context Protocol - MCPの仕様
• Civitai - AIモデル共有プラットフォーム
• MCP Servers - 公式MCPサーバーの実装

サポート

• 🐛 バグ報告：GitHub Issues
• 💡 機能リクエスト：GitHub Discussions
• 📚 ドキュメント：Civitai API Reference
• 🔧 MCPドキュメント：Model Context Protocol