Civitai MCP

MCP-сервер для работы с Civitai прямо из ассистента. Ищите модели по названию/типу/базовой модели, смотрите превью и примеры генерации, берите параметры генерации из любой картинки (локальной или с Civitai), скачивайте файлы на диск или получайте прямую ссылку для больших моделей.

Написан на Python (FastMCP) + httpx + Pillow.

Возможности

• 🔎 Поиск моделей — фильтры по типу, базовой модели, тегу, автору, сортировка.

• 🖼️ Визуальный выбор — превью в результатах поиска и галерея примеров генерации (готовые URL + лёгкие превьюшки).

• 🧬 Параметры генерации — читает prompt/seed/steps/sampler/… из локального PNG (A1111/ComfyUI) или jpg/webp (EXIF/XMP), а также с картинок Civitai.

• ⬇️ Скачивание — файл версии на диск (стриминг, атомарная запись, докачка) или прямая подписанная ссылка для больших моделей.

Related MCP server: MCP Boilerplate

Инструменты

Типовой сценарий: search_models → посмотреть preview/get_model_images → выбрать version.id → download_model(version_id, dest_dir) или get_download_url(version_id).

Картинки

Превью и галерея приходят готовыми URL-ами CDN. У каждой картинки есть:

• url — оригинал;

• thumb — лёгкая версия (width=450, строится трансформом CDN);

• nsfwLevel, width, height, type (image/video), prompt.

Параметры генерации изображения

Два источника, потому что это разные вещи:

• read_image_params(path) — локальный файл. Читает офлайн зашитые метаданные: PNG Automatic1111/Forge (чанк parameters), ComfyUI (prompt/workflow), а для jpg/webp — EXIF UserComment/ImageDescription и XMP через Pillow. Возвращает prompt, negativePrompt, params (steps/sampler/cfg/seed/size/model…), source (откуда взято) и сырую строку. Работает для любой сгенерированной картинки, даже не с Civitai. PNG разбирается и без Pillow; jpg/webp — с Pillow (входит в requirements).

• get_image_meta(image_id) — картинка на Civitai по её id. Важно: у публичной ленты meta часто null (Civitai его скрывает). У примеров версии модели (get_model_version.images) meta есть всегда, поле meta_available это показывает.

Большие модели → ссылка вместо скачивания

• get_download_url(version_id) — всегда возвращает direct_url (подписан, ~1 час) и page_url (постоянная страница модели).

• download_model(..., max_mb=200) — если файл больше лимита, вернёт status: "too_large" с direct_url вместо загрузки на диск.

Генерация изображений

Официальный Civitai Orchestration API. Модель задаётся model_version_id (AIR берётся из API автоматически) или готовым model_air; ecosystem (sd1/sdxl/flux1…) определяется из AIR. Готовый AIR версии также виден в поле air ответа get_model_version.

⚠️ Генерация тратит реальный Buzz. generate_image без confirm=true не запускает генерацию — только возвращает предполагаемую стоимость (whatif). Для реального запуска — повторный вызов с confirm=true. Проверка баланса и insufficientBuzz выполняется до списания.

estimate_generation(prompt, model_version_id=…)      → {cost:{buzz, insufficientBuzz}}
generate_image(prompt, model_version_id=…)           → preview со стоимостью (confirm=false)
generate_image(prompt, model_version_id=…, save_dir=…, confirm=true)
                                                     → {status, workflowId, images:[{url, path}]}
get_workflow(workflow_id)                            → статус/картинки для долгих задач

Ориентир по цене: SD1.5 512×512 / 20 шагов ≈ 4 Buzz, SDXL 1024×1024 / 25 шагов ≈ 10 Buzz.

Полный набор параметров generate_image / estimate_generation

Движки различаются именами полей — MCP подставляет их сам: sampler↔sampleMethod, scheduler↔schedule, strength↔denoiseStrength. Скачивание результата ретраит временные 5xx CDN.

LoRA — несколько сразу:

generate_image(prompt, model_version_id=128713,
  loras={"62833": 0.8, "urn:air:sd1:lora:civitai:82098@87153": 0.5}, confirm=true)

img2img:

generate_image(prompt="daytime, clear sky", model_version_id=128713,
  operation="createVariant", source_image="https://.../src.jpeg", strength=0.6, confirm=true)

LoRA/embeddings/VAE должны быть той же экосистемы, что и чекпойнт (sd1↔sd1, sdxl↔sdxl).

Баланс Buzz

get_buzz_balance() возвращает балансы кошельков (yellow/blue/green) текущего аккаунта по ключу.

⚠️ Неофициально. Использует внутренний tRPC-эндпоинт сайта (buzz.getBuzzAccount), а не публичный /api/v1. Он не документирован и может перестать работать без предупреждения — в отличие от остальных инструментов.

Установка

py -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements.txt

Ключ API

Ключ берётся из переменной окружения CIVITAI_API_KEY (fallback — файл apikey.txt рядом с server.py). Скачивание файлов требует валидный ключ; поиск/метаданные работают и без него.

Получить ключ: civitai.com → Account settings → API Keys.

Подключение к Claude Code

claude mcp add civitai -e CIVITAI_API_KEY=<ваш-ключ> -- H:/CivitaiMcp/.venv/Scripts/python.exe H:/CivitaiMcp/server.py

Или вручную в .mcp.json (см. mcp.example.json):

{
  "mcpServers": {
    "civitai": {
      "command": "H:/CivitaiMcp/.venv/Scripts/python.exe",
      "args": ["H:/CivitaiMcp/server.py"],
      "env": { "CIVITAI_API_KEY": "<ваш-ключ>" }
    }
  }
}

Примеры значений

• types: Checkpoint, LORA, LoCon, VAE, TextualInversion, Hypernetwork, Controlnet

• base_models: SD 1.5, SDXL 1.0, Pony, Illustrious, Flux.1 D

• sort: Highest Rated, Most Downloaded, Newest

• file_format: SafeTensor, PickleTensor; size: full/pruned; fp: fp16/fp32/bf16

Ошибки скачивания

401 — неверный ключ · 403 — early-access/ограничение автора · 429 — лимит 24ч.

Скилл: как правильно генерировать

skills/civitai-generation/SKILL.md — глубокий гайд по параметрам генерации: выбор семейства модели (SD1.5 / SDXL / Pony / Illustrious / NoobAI / Flux) и его диалект промпта, сэмплеры/планировщики, CFG/steps/резолюции, LoRA/ embeddings/VAE, img2img и NSFW-конвенции (score_*, rating_explicit, danbooru-теги). Составлен по материалам Civitai. Агент-клиент (Claude Code и т.п.) подхватывает скилл из папки skills/ — либо скопируйте её в свой каталог скиллов.

Лицензия

MIT.

🤖 Built with Claude Code.