Models

​

download_model

• action:“download” — Download a model file to the connected ComfyUI’s models directory from a URL (HuggingFace, direct HTTP(S), s3://, or Azure Blob). Requires url + target_subfolder. PREFER this over a raw shell download (curl/wget) for model weights: it lands the file in the right models/ subfolder. LOCAL ComfyUI: streams to disk and surfaces live progress in the panel download tray. REMOTE ComfyUI: dispatches the fetch to the ComfyUI host via the ComfyUI-Manager install-model HTTP API (downloaded server-side; a per-request auth header can’t be forwarded). This requires the host’s Manager to run with network_mode=personal_cloud (or loopback) and a permissive security level — a stricter gate silently rejects the download, and Manager reports the queue task ‘done’ even on failure, so a remote dispatch does not guarantee the file landed. target_subfolder accepts any relative subfolder (incl. nested, e.g. ‘loras/<subdir>’).
• action:“status” — Check on downloads started by action:“download” / action:“download_civitai”. Reports each download’s state (downloading / done / error / cancelled), its destination path once it lands, and byte progress when the panel progress channel is enabled. Use this after a download reports it is still running — that means the transfer is in flight, NOT that it failed. Across an AGENT/sidebar session reconnect a download this MCP streams locally keeps running and is normally resolvable by id or by url. An ORCHESTRATOR RESTART is different: a record carried across one reports only that this MCP STOPPED WATCHING — not that the bytes stopped, which it does not check. READ THE NOTE ON THAT RECORD before acting: it distinguishes a local stream (nothing is writing it; re-issue) from a ComfyUI-Manager dispatch (the fetch runs on the ComfyUI host, which a restart here does not touch, so re-issuing writes a second copy to the same destination and CORRUPTS the model). And NOT FOUND NEVER MEANS STOPPED: both the cross-session record and the carry-over are written best-effort, so their absence is evidence of nothing. Omit id and url to list every tracked download. A previous session’s download whose heartbeat has gone stale is reported with a stale-heartbeat NOTE: action:“cancel” can close it once the writer is proven gone, and re-issuing action:“download” then resumes or restarts it. Read-only.
• action:“cancel” — Cancel ONE in-flight download by its id (from action:“status” or from the download that started it) — REQUIRED, and it must be the id of the download you mean, since a wrong id stops someone else’s transfer. Aborts only that download’s transfer; other downloads keep running. An id that names no tracked download is reported as such, not silently treated as success. The partially-downloaded bytes are left on disk as a resumable .partial and are NEVER reported as a completed file, so nothing corrupt lands in your models directory; re-issuing the same download later resumes where it left off. Idempotent: cancelling an already-finished, failed, or already-cancelled download just reports its current state. A download whose AbortController lives in ANOTHER live session cannot be aborted from here (stop it from the panel download tray) — but a download left ‘downloading’ by a session that is PROVEN gone (heartbeat stale AND its process no longer exists) CAN be cancelled from here: the stale record is closed as cancelled, after which re-issuing action:“download” resumes the leftover .partial or restarts cleanly. While the writer cannot be proven gone, the cancel refuses rather than risk two writers on one file. NOTE: for a download dispatched to a REMOTE ComfyUI via ComfyUI-Manager (server-side fetch), the local job is marked cancelled but the host may keep fetching — there is no Manager API to stop it.
• action:“search” — Search HuggingFace Hub for models usable in ComfyUI (checkpoints, LoRAs, VAEs, ControlNets, etc.); query is required. Read-only and network-only: queries HuggingFace over HTTP, does NOT require a running ComfyUI or COMFYUI_PATH and does not download anything. Returns a ranked list with modelId, author, downloads, likes, and tags. Pick a result’s download URL and pass it to action:“download”. For CIVITAI searches (‘find a Flux LoRA on Civitai’) use action:“search_civitai” instead — it filters by type + base model and returns ids for action:“download_civitai”. For packs of custom nodes (not models) use search_custom_nodes.
• action:“search_civitai” — Search CivitAI by keyword for checkpoints, LoRAs, embeddings, VAEs, and ControlNets — THE action for ‘find me a <base model> LoRA on Civitai’. Read-only and network-only (public CivitAI REST API; no token or running ComfyUI required; CIVITAI_API_TOKEN unlocks gated results). Filter by types (LORA, Checkpoint, TextualInversion, VAE, Controlnet, …) and base_models (CivitAI labels: ‘Flux.1 D’, ‘SDXL 1.0’, ‘SD 1.5’, ‘Pony’, ‘Illustrious’, ‘Wan Video’) — ALWAYS pass base_models when the user’s checkpoint family is known, so results actually fit their setup. Each hit returns the model_id and version_id that action:“download_civitai” takes directly, plus trigger words to use in the prompt after installing. Flow: action:“search_civitai” → pick a hit → action:“download_civitai” {model_version_id, target_subfolder} → wire/prompt with the trained words. Pass creator (exact username, e.g. from action:“search_creators”) to list ONE creator’s models — with or without a query; at least one of the two is required. SFW-only by default. For HuggingFace search use action:“search”.
• action:“search_creators” — Find CivitAI CREATORS — THE action for ‘who are the top creators on Civitai’ and ‘find creator <name>’. Read-only and network-only (no token or running ComfyUI required). Two modes: with NO query it returns the site’s creator LEADERBOARD (civitai.com/leaderboard — rank, score, downloads, likes; pick a board: ‘overall’ [default], ‘overall_90’ [last 90 days], ‘overall_nsfw’ [mature], ‘new_creators’ [first model <30 days ago]); with a query it searches usernames (public /api/v1/creators; partial match, returns model counts, NOT ranked). Each hit’s username feeds action:“search_civitai” {creator: <username>} directly. SCOPE CAVEAT: the /api/v1/creators index only lists creators who have published MODELS. A creator who posts only images/videos (no models) legitimately returns 0 hits here — that is a gap in this endpoint, NOT proof the creator doesn’t exist. For a media-only creator, browse their images via the panel CivitAI browser (panel_open_civitai {creator}) or the logged-in browser session instead.
• action:“download_civitai” — Download a model from CivitAI into the connected ComfyUI’s models/ directory. Requires target_subfolder plus at least one of model_id / model_version_id. Resolves a CivitAI model id (latest version) or a model-version id to a download URL via the CivitAI REST API. LOCAL ComfyUI (COMFYUI_PATH set): streams the file to disk under <COMFYUI_PATH>/models/<target_subfolder>/ and returns the saved absolute path. REMOTE ComfyUI: dispatches the download to the ComfyUI host via the ComfyUI-Manager install-model HTTP API (fetched server-side). Gated/early-access models require CIVITAI_API_TOKEN locally (sent as a bearer header, never in the URL); remote Manager-side fetches rely on tokens configured on the ComfyUI host. NOTE (remote): the server-side install requires the host’s ComfyUI-Manager to run with network_mode=personal_cloud (or loopback) and a permissive security level; a stricter gate silently rejects the download, and Manager reports the queue task ‘done’ even on failure — so a remote dispatch does not guarantee the file landed.
• action:“resolve_missing” — Find the model files a workflow needs but this ComfyUI does NOT have, and search CivitAI + HuggingFace for installable candidates. THE action for ‘this Template says a model is missing — go get it’. Detects by comparing each model widget against the option list the server actually publishes, so it covers checkpoints, LoRAs, VAEs, ControlNets, UNets, CLIP and custom-pack model types without any per-node mapping. Each candidate reports size, source, precision/quantisation (fp16 / fp8 / GGUF Q4_K_M …) and whether it FITS this GPU’s VRAM — so when the exact file is too big you can see the quantised variant that isn’t. Read-only: it downloads nothing. Pass a chosen candidate to action:“download” (url) or action:“download_civitai” (id), using the reported directory as target_subfolder. For missing custom NODE PACKS (not models) use list_packs (action:“install_deps”) instead.

​

Parameters

​

Examples

{
  "tool": "download_model",
  "arguments": {
    "action": "search",
    "query": "flux schnell",
    "limit": 5
  }
}

{
  "tool": "download_model",
  "arguments": {
    "action": "download",
    "url": "https://huggingface.co/black-forest-labs/FLUX.1-schnell/resolve/main/flux1-schnell.safetensors",
    "target_subfolder": "checkpoints"
  }
}

{
  "tool": "download_model",
  "arguments": {
    "action": "status"
  }
}

{
  "tool": "download_model",
  "arguments": {
    "action": "resolve_missing",
    "workflow": {
      "4": {
        "class_type": "CheckpointLoaderSimple",
        "inputs": {
          "ckpt_name": "sd_xl_base_1.0.safetensors"
        }
      },
      "9": {
        "class_type": "SaveImage",
        "inputs": {
          "filename_prefix": "portrait",
          "images": [
            "8",
            0
          ]
        }
      }
    }
  }
}

​

list_local_models

• action:“list” — List model files available to the connected ComfyUI, grouped by type. Read-only. Queries ComfyUI’s /models REST endpoint first (works with remote ComfyUI and respects extra_model_paths.yaml — symlinked / mounted dirs the install-path filesystem scan would miss), then falls back to a filesystem scan of COMFYUI_PATH/models/ when the REST endpoint is unavailable. Size and modified time are only available on the filesystem fallback path. Use to see which models are already available before generating or downloading; use download_model action:“search” to discover new models on HuggingFace, then action:“download” to fetch them. For models fetched via download_model action:“download_civitai”, any CivitAI trigger/activation words and base model are shown inline (read from the <file>.civitai.json sidecar) — apply those trigger words in your prompt when generating with that model. A civitai: line under an entry is that model’s CivitAI page URL (modelId + INSTALLED modelVersionId, from the same sidecar) — use it to reference the source or check for newer versions.
• action:“remove” — DELETES a model FILE from the local ComfyUI models directories. path is REQUIRED and is a file path relative to models/. THIS IS DESTRUCTIVE AND HAS NO UNDO: the file is unlinked, not moved to a recycle bin, and a large checkpoint can take hours to re-download — confirm the exact path with the user (action:“list” shows it) before calling. Resolves the path across ALL configured roots — the primary <COMFYUI_PATH>/models AND every directory in extra_model_paths.yaml / extra_models_config.yaml (e.g. models stored on another drive like E:) — the same roots ComfyUI loads from. The path must stay within a known root (path traversal and absolute escapes are rejected), and a directory is refused. LOCAL-ONLY: deletes from the local filesystem, so it is not supported against a remote ComfyUI (remove the file on the host). Do NOT confuse this with action:“remove_path”, which edits a config file and deletes nothing.
• action:“embeddings” — List textual-inversion embeddings installed on the connected ComfyUI server (read from its /api/embeddings endpoint, i.e. the models/embeddings folder). Requires a running, reachable ComfyUI (local or remote); takes no other parameters. Returns the embedding names; reference them in positive or negative prompts as embedding:name (e.g. embedding:easynegative). Read-only.
• action:“list_paths” — View ComfyUI extra search-path config for standalone/manual installs and ComfyUI Desktop. Read-only. Resolves LIVE-FIRST: the file the running ComfyUI actually reads (its —extra-model-paths-config, else the extra_model_paths.yaml beside its main.py), falling back to the local heuristic only when no server is reachable — <ComfyUI root>/extra_model_paths.yaml (COMFYUI_PATH, else the saved default workspace from workspace action:“set_default”) or the Desktop app-data extra_models_config.yaml. Reports generic categories, so model categories and custom_nodes entries are both visible when present. Because it is read-only it never refuses a reachable LOCAL server just because its argv does not prove which file it reads: it shows the server-named config when that file exists here, else the local auto-selected one, always labelled as unconfirmed rather than presented as the live server’s. action:“add_path”/action:“remove_path” still refuse in that state — a write to an unproven file would be a silent no-op.
• action:“add_path” — Add a directory to a ComfyUI extra search-path YAML config; category + path are REQUIRED. Use this for model categories such as checkpoints/loras/vae and, on ComfyUI builds that support it, custom_nodes. Writes the config file and returns the updated view; restart ComfyUI to apply.
• action:“remove_path” — Remove a directory from a ComfyUI extra search-path YAML config; category + path are REQUIRED. Matches the stored path exactly. This edits the YAML only — it deletes NO model files and frees no disk space (that is action:“remove”). Restart ComfyUI after removing an active path.

​

Parameters

​

Examples

{
  "tool": "list_local_models",
  "arguments": {
    "action": "list",
    "model_type": "checkpoints"
  }
}

{
  "tool": "list_local_models",
  "arguments": {
    "action": "remove",
    "path": "loras/old-character-v1.safetensors"
  }
}

{
  "tool": "list_local_models",
  "arguments": {
    "action": "add_path",
    "category": "checkpoints",
    "path": "E:/Models/checkpoints"
  }
}

​

clear_vram

​

Parameters

​

Example

{
  "tool": "clear_vram",
  "arguments": {}
}

​

model_metadata

• action:“read” — Read a model file’s CURRENT embedded metadata + evidence, for curating it. Returns classify (asset_type/base/precision/rank), the current model_card and prompt_director namespaces, read-only modelspec, top training tags (ss_tag_frequency), the Civitai description, and example prompts. Call this FIRST when the user wants to improve/curate a model’s embedded .safetensors metadata, so you propose from real data. NOTE: this is the embedded-in-the-tensor metadata (model_card/prompt_director/modelspec/ss_*) — NOT the separate lora_catalog. category = ComfyUI model folder (‘loras’,‘checkpoints’,‘vae’,…); name = filename incl. .safetensors — BOTH required for read/propose, e.g. {action:“read”, category:“loras”, name:“my_model.safetensors”}. DEPENDENCY: the curated read proxies the OPTIONAL ‘comfyui-model-explorer’ custom node. When that node is absent but the model file is reachable on the LOCAL filesystem, the tool does NOT hard-fail — it degrades to a structured ‘model_explorer: unavailable’ result with local evidence (file stat, the download_model action:“download_civitai” sidecar, and the raw embedded safetensors metadata). Without local filesystem access, it still returns the same structured unavailable result, but without file evidence.
• action:“propose” — PROPOSE cleaned embedded metadata into the user’s diff-review window. This does NOT write the file — the user sees your proposed fields vs current, edits/discusses, and their Confirm does the write. Call whenever you have a proposal OR the user asks you to revise one; each call REPLACES the live proposal, so send the FULL field set you’re proposing. Include only fields you’re confident about. Keys: display_name, description_clean, semantic_intent, prompt_guidance, preservation_guidance, trigger_tokens[] (EXACT tokens — never invent), activation_phrases[], negative_tokens[], tags[], compatible_families[], default_strength_model, default_strength_clip, strength_min, strength_max. NEVER write metadata directly.
• action:“fetch_civitai” — READ-ONLY: pull this model’s data from Civitai (civitai.com) — the rich description, trainedWords, example prompts (with the prompt text used in the sample images), tags, nsfw flag, and source_url — WITHOUT writing anything. Call this when the embedded metadata is thin (empty model_card/prompt_director, no ss_tag_frequency) or to flesh out details before proposing. Treat the result as RAW input: distill the (often marketing-heavy) description, and MINE THE EXAMPLE PROMPTS for the real trigger — the trigger is frequently ONLY in the sample prompts even when trainedWords is EMPTY (e.g. every prompt starting with ‘photo in the style of X’ means X is the trigger). Adult models (civitai.red) resolve through this same API. Then clean it up and call action:“propose”. DEPENDENCY: automatic by-hash lookup uses the OPTIONAL ‘comfyui-model-explorer’ custom node. If that node isn’t installed, pass ‘version_id’ (the CivitAI modelVersionId) and this action degrades to CivitAI’s public REST API directly — no node, no auth. Without both the node AND a version_id it returns a clear ‘optional feature unavailable’ message rather than enriching.

​

Parameters

​

Example

{
  "tool": "model_metadata",
  "arguments": {
    "action": "read",
    "category": "loras",
    "name": "my_model.safetensors"
  }
}