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 文档：模型上下文协议