Civitai MCP Server

🚀 Civitai MCP 服務器

Civitai MCP 服務器是一個模型上下文協議（MCP）服務器，它能讓 AI 助手全面訪問 Civitai 上豐富的 AI 模型、創作者信息和生成內容。你可以通過喜愛的 MCP 兼容 AI 助手，無縫地瀏覽、搜索和發現 AI 模型。

✨ 主要特性

🔍 模型發現

• 高級搜索：可根據類型、創作者、標籤等靈活篩選條件查找 AI 模型。
• 分類瀏覽：按類型（檢查點、LoRA、ControlNet 等）瀏覽模型。
• 熱門與趨勢：發現下載量最多和評分最高的模型。
• 最新模型：及時瞭解新上傳的模型。
• 哈希查找：通過文件哈希查找模型以進行驗證。

👨‍💻 創作者與社區

• 創作者資料：瀏覽和搜索模型創作者。
• 創作者作品集：查看特定創作者的所有模型。
• 標籤系統：通過 Civitai 全面的標籤系統探索模型。

🖼️ 生成內容

• 圖像畫廊：瀏覽帶有詳細元數據的 AI 生成圖像。
• 生成參數：獲取提示、設置和模型信息。
• 社區展示：發現社區中令人鼓舞的創作。

📊 模型智能

• 詳細模型信息：提供完整的模型規格、版本和文件信息。
• 版本歷史：跟蹤模型的更新和改進。
• 下載鏈接：支持身份驗證，可直接訪問模型下載鏈接。
• 內容安全：獲取 pickle 和病毒安全掃描結果。

📦 安裝指南

前提條件

• 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 密鑰。
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 - 完整的穩定擴散模型
• LORA - 低秩適應模型
• TextualInversion - 文本嵌入模型
• Hypernetwork - 超網絡模型
• 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 - 列出標籤
• ✅ 支持身份驗證的下載鏈接

支持的模型類型

• Checkpoint：完整的穩定擴散模型
• LORA：低秩適應模型
• TextualInversion：文本嵌入模型
• Hypernetwork：超網絡模型
• AestheticGradient：美學梯度模型
• Controlnet：控制網絡模型
• Poses：姿勢模型

內容過濾

服務器支持 Civitai 的內容過濾系統：

• NSFW 內容級別（無、輕度、成熟、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

🤝 貢獻代碼

我們歡迎貢獻！請查看我們的 貢獻指南 瞭解詳細信息。

開發設置

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 文件。

相關項目

• 模型上下文協議 - MCP 規範
• Civitai - AI 模型共享平臺
• MCP 服務器 - 官方 MCP 服務器實現

支持

• 🐛 錯誤報告：GitHub 問題
• 💡 功能請求：GitHub 討論
• 📚 文檔：Civitai API 參考
• 🔧 MCP 文檔：模型上下文協議