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. 複製密鑰並設置為環境變量

📚 詳細文檔

MCP 客戶端設置

將服務器添加到你的 MCP 客戶端配置中：

Claude 桌面版

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "civitai": {
      "command": "node",
      "args": ["/path/to/civitai-mcp-server/dist/index.js"],
      "env": {
        "CIVITAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

其他 MCP 客戶端

根據客戶端文檔進行配置，使用以下信息：

• 命令：node /path/to/civitai-mcp-server/dist/index.js
• 傳輸方式：stdio
• 環境變量：CIVITAI_API_KEY=your_key

💻 使用示例

基礎模型搜索

搜索與動漫相關的 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"

可用工具

🔧 技術細節

模型類型

• 檢查點（Checkpoint）：完整的穩定擴散模型
• LoRA：低秩自適應模型
• 文本嵌入（TextualInversion）：文本嵌入模型
• 超網絡（Hypernetwork）：超網絡模型
• 美學梯度（AestheticGradient）：美學梯度模型
• ControlNet：ControlNet 模型
• 姿態（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：ControlNet 模型
• 姿態（Poses）：姿態模型

內容過濾

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

• NSFW 內容級別（無、輕度、成熟、限制級）
• 商業使用權限
• 模型許可選項

錯誤處理

服務器包含全面的錯誤處理機制，可處理以下情況：

• 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 服務器實現

支持

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