civitai-mcp-ultimate

---
name: civitai-mcp-ultimate
description: Ultimate MCP server for Civitai — search models, browse top images with prompts, download LoRAs/Checkpoints, analyze trends. Use when user asks about AI models, LoRAs, checkpoints, Stable Diffusion, Flux, image generation prompts, or Civitai.
---

# Civitai MCP Ultimate — 14 Tools Reference

## Quick Tool Map

| Goal | Tool | Key Params |
|------|------|-----------|
| Find models by name | `search_models` | `query` (Meilisearch), `types`, `base_model` |
| Find models by creator | `search_models` | `username` (most reliable) |
| Batch fetch by IDs | `search_models` | `ids=[123, 456]` |
| Full model details | `get_model` | `model_id` |
| Version details + hashes | `get_model_version` | `version_id` |
| Identify model from file | `get_model_version_by_hash` | SHA256/AutoV2/CRC32/BLAKE3 |
| Top checkpoints | `get_top_checkpoints` | `base_model`, `period` |
| Top LoRAs | `get_top_loras` | `base_model`, `nsfw` |
| Browse images/videos | `browse_images` | `model_id`, `content_type`, `tag`, `base_model` |
| Trending images/videos | `get_top_images` | `sort`, `period`, `content_type`, `browsing_level` |
| Example images for model | `get_model_images` | `model_id` |
| Extract best prompts | `get_image_generation_data` | `model_id` |
| Download URL | `get_download_url` | `version_id` |
| Download commands | `get_download_info` | `model_id`, `comfyui_path` |

## Common Recipes (Quick Reference)

### Top image by likes yesterday, specific base model
```
get_top_images(sort="Most Reactions", period="Day", content_type="image", base_model="Flux.1 D", limit=1)
```

### Top video by comments this week
```
get_top_images(sort="Most Comments", period="Week", content_type="video", limit=1)
```

### Most popular SDXL model this month
```
search_models(base_model="SDXL 1.0", sort="Most Downloaded", period="Month", limit=1)
```

### Top 5 images from the most popular Flux model today
```
search_models(types=["Checkpoint"], base_model="Flux.1 D", sort="Most Downloaded", period="Day", limit=1)
  -> get model_id
get_model_images(model_id=ID, limit=5)
```

### Community images for a model (sorted by reactions)
```
browse_images(model_id=ID, sort="Most Reactions", period="Month", limit=5)
```
**NOTE**: `model_id` auto-resolves to the latest version. To see images from a specific version, use `model_version_id` directly:
```
get_model(model_id=ID)  # -> see all versions with IDs
browse_images(model_version_id=VERSION_ID, sort="Most Reactions", period="AllTime", limit=5)
```

### Most popular NSFW image this month with prompt
```
get_top_images(sort="Most Reactions", period="Month", content_type="image", browsing_level="XXX", has_meta=true, limit=1)
```

### Find a specific LoRA by name (e.g. hands fix)
```
search_models(query="hands fix", types=["LORA"], sort="Most Downloaded", limit=5)
```
**NOTE**: Text search uses Meilisearch (fast, accurate). Combining `query` + `types` + `base_model` works via Meilisearch! Falls back to REST API only when using REST-only params (ids, favorites, license filters).

### Top 10 LoRA by downloads this month
```
get_top_loras(sort="Most Downloaded", period="Month", limit=10)
```

### Anime images from ComfyUI, only with metadata
```
get_top_images(tag="anime", tools="ComfyUI", has_meta=true, period="Week", limit=5)
```

### Only videos made on Civitai
```
get_top_images(content_type="video", made_on_site=true, period="Month", limit=5)
```

### Only original works (no remixes)
```
get_top_images(originals_only=true, period="Week", limit=10)
```

### XXX content only
```
get_top_images(browsing_level="XXX", sort="Most Reactions", period="Day", limit=5)
browse_images(browsing_level="X,XXX", content_type="video", period="Week", limit=3)
```

## Image/Video Cache

All images and videos are **automatically downloaded** to `~/.civitai-mcp-cache/`:
- Images: 512px thumbnails (saves bandwidth)
- Videos: original quality
- Auto-cleanup: files older than 24h deleted on server startup
- Local paths returned in output — use **Read tool** to preview images

## Workflows

### 1. Find the Best LoRA for a Style

```
get_top_loras(base_model="Flux.1 D", period="Week", limit=10)
  -> pick model_id
get_model(model_id=ID)
  -> read trigger words, description, versions
get_image_generation_data(model_id=ID, limit=5)
  -> extract prompts, settings, LoRA weight
get_download_info(model_id=ID, comfyui_path="C:/ComfyUI/models")
  -> ready-to-paste curl/wget/PowerShell
```

### 2. Prompt Mining

```
get_top_images(sort="Most Reactions", period="Week", has_meta=true, limit=10)
  -> each image has: prompt, negative prompt, steps, CFG, sampler, seed, LoRAs
```

For a specific model:
```
get_image_generation_data(model_id=ID, sort="Most Reactions", limit=5)
  -> only images WITH metadata
```

### 3. Download Model to ComfyUI

```
get_download_info(model_id=858800, comfyui_path="D:/ComfyUI/models")
```
Returns: curl + wget + PowerShell commands, ComfyUI subfolder, all hashes, scan results.

### 4. Identify Unknown .safetensors File

```
get_model_version_by_hash(hash="E837144C55")  # AutoV2 hash
```

### 5. Compare Models by Popularity

```
get_top_checkpoints(base_model="Flux.1 D", period="Month", sort="Most Downloaded", limit=20)
get_top_checkpoints(base_model="SDXL 1.0", period="Month", sort="Most Downloaded", limit=20)
```

## Enum Cheat Sheet

### Model Types
`Checkpoint`, `LORA`, `LoCon`, `TextualInversion`, `Hypernetwork`, `Controlnet`, `Poses`, `VAE`, `Upscaler`, `Wildcards`, `MotionModule`, `Workflows`, `Other`

### Base Models
| Category | Values |
|----------|--------|
| SD 1.x | `SD 1.4`, `SD 1.5`, `SD 1.5 LCM`, `SD 1.5 Hyper`, `SD 2.0`, `SD 2.1` |
| SDXL | `SDXL 1.0`, `SDXL Lightning`, `SDXL Hyper` |
| Flux | `Flux.1 S`, `Flux.1 D`, `Flux.1 Krea`, `Flux.1 Kontext`, `Flux.2 D`, `Flux.2 Klein 9B/4B` |
| Anime | `Pony`, `Pony V7`, `Illustrious`, `NoobAI`, `Anima` |
| Z-Image | `ZImageBase`, `ZImageTurbo` |
| Other | `Qwen`, `Chroma`, `HiDream`, `AuraFlow`, `Hunyuan 1`, `Kolors`, `PixArt a/E`, `Lumina` |
| Video | `CogVideoX`, `Hunyuan Video`, `LTXV`, `LTXV2`, `LTXV 2.3`, `Mochi`, `Wan Video 1.3B t2v`, `Wan Video 14B t2v`, `Wan Video 14B i2v 480p/720p`, `Wan Video 2.2 TI2V-5B/I2V-A14B/T2V-A14B`, `Wan Video 2.5 I2V/T2V` |

### Sort
- Models (Meilisearch): `Most Downloaded`, `Highest Rated`, `Most Collected`, `Most Comments`, `Most Tipped`, `Newest`, `Oldest`
- Models (REST API): `Highest Rated`, `Most Downloaded`, `Newest`
- Images/Videos: `Most Reactions`, `Most Comments`, `Most Collected`, `Newest`, `Oldest`

### Period
`AllTime`, `Year`, `Month`, `Week`, `Day`

### Browsing Level
`PG` (1), `PG-13` (2), `R` (4), `X` (8), `XXX` (16) — comma-separated for multiple, e.g. "X,XXX"

### Content Type
`image`, `video`

### NSFW Levels (legacy)
`None`, `Soft`, `Mature`, `X`

### Image Modifiers
`has_meta`, `made_on_site`, `originals_only`, `remixes_only` — boolean flags

### Image Filters
`tag` (e.g. "anime"), `base_model` (e.g. "Flux.1 D"), `tools` (e.g. "ComfyUI"), `techniques` (e.g. "txt2img")

### ComfyUI Folder Mapping
`Checkpoint` -> `checkpoints/`, `LORA`/`LoCon` -> `loras/`, `TextualInversion` -> `embeddings/`, `Controlnet` -> `controlnet/`, `VAE` -> `vae/`, `Upscaler` -> `upscale_models/`

## Known Quirks

1. **search_models via REST API: query + types/base_model = empty results**. Fixed in v0.2.0 — text search now uses Meilisearch which supports combining query with type/baseModel/tag/username filters. REST API fallback still has this limitation.
2. **search_models by username**: Most reliable search method. Always prefer `username="CreatorName"`.
3. **get_creators**: Civitai endpoint is slow (30s+) and may return 500. Use `search_models(username=...)` instead.
4. **"Most Reactions" sort cursor bug**: Returns null cursor, preventing pagination beyond page 1.
5. **License filters** (`allow_no_credit`, etc.): Civitai API may return 400.
6. **modelId ignored on /images endpoint**: Civitai API ignores `modelId` param — only `modelVersionId` works. Fixed in v0.2.1: `browse_images`, `get_model_images`, and `get_image_generation_data` now auto-resolve `model_id` to `model_version_id` (uses latest version). You can still pass `model_version_id` directly to target a specific version.
7. **browsingLevel**: Bitmask system (1=PG, 2=PG-13, 4=R, 8=X, 16=XXX). Undocumented but stable.
8. **content_type/tag/tools/techniques**: All undocumented API params but verified working 2026-03-24.
9. **get_tags**: No NSFW filter available. Returns generic tags (character, anime, woman...) without model counts. Cannot query "top NSFW tags" — use `browse_images(browsing_level="X,XXX")` and inspect tags on returned images instead.

## Environment Variables

```
CIVITAI_API_KEY     — Civitai API key (NSFW access + higher rate limits)
CIVITAI_MCP_LANG    — en (default) | ru
COMFYUI_MODELS_PATH — default ComfyUI models path for download_info
MEILISEARCH_KEY     — Meilisearch search-only key (optional, has built-in default)
```