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