Workflow Execution

​

enqueue_workflow

• action:“enqueue” — Submit an API-format workflow you are already holding (one you built with create_workflow, loaded with get_workflow, or edited with create_workflow action:“modify”). Returns immediately with the prompt_id and queue position; does NOT wait for completion. Seed values in the workflow are used EXACTLY as supplied — they are NOT re-randomized, so a run is reproducible by resubmitting the same workflow (for a fresh-seed re-run of a past job, use action:“rerun”). workflow is required. Use queue (action:“status”) to check progress later, or get_history (action:“list”) to retrieve results and images after completion.
• action:“rerun” — Re-run the workflow behind a PREVIOUS generation. Retrieves the prompt graph from execution history (by prompt_id, or the most recent run when omitted — chosen by ComfyUI’s queue number, same logic as get_history) and re-enqueues it, optionally applying inputs overrides. Seeds are re-randomized (within each node’s declared range) unless disable_random_seed is set or the seed is pinned via inputs. Returns the new prompt_id and the source prompt_id it came from. Clear error if no matching history exists. To re-run from a registered ASSET instead of history, use generate_image (action:“regenerate”).
• action:“run_url” — Read (and optionally execute) a SHARED workflow from a URL. Fetches the workflow JSON, accepts API-format prompt graphs or UI-format exports (UI is auto-converted via the same converter as get_workflow), validates it, and summarizes it. Supports raw .json links and GitHub blob/raw URLs (blob is normalized to raw); other share hosts that need a site API return a clear ‘paste the raw JSON URL’ error. The fetch is bounded (http/https only, timeout + size cap, loopback/private/metadata IPs rejected to prevent SSRF). READ-ONLY unless run=true; when run=true it enqueues the workflow (applying optional inputs overrides) and returns the prompt_id. url is required.
• action:“template_schema” — Get a template’s OVERRIDABLE run-time parameters (its ‘slots’) BEFORE running it. Pass a bundled pack name (from list_packs action:“list”) or a custom-node-contributed workflow template name (from list_packs action:“list_templates”) as template. Returns slots — the meaningful knobs: positive/negative prompt, seed, steps, cfg, sampler/scheduler, width/height, checkpoint/LoRA/model files, denoise, batch_size, input image — plus other_slots (every remaining overridable widget), each with a stable key “<nodeId>.<widget_name>”, semantic role, type, current value, and min/max/options where the node schema is known. Read-only. Feed the keys DIRECTLY into action:“run_template“‘s overrides (same convention) for a schema→run round-trip.
• action:“run_template” — ONE-SHOT: run a named workflow template (a bundled pack from list_packs) with optional overrides. Resolves the template’s expert graph, applies overrides, and enqueues it — replacing the manual list_packs (action:“read_workflow”) → create_workflow (action:“modify”) → action:“enqueue” chain. Override keys are ‘<nodeId>.<widget_name>’ (e.g. {‘6.text’: ‘a cat’, ‘3.seed’: 42}) — the SAME keys action:“template_schema” reports (when available), so schema→run round-trips; only widget values can be overridden, never graph connections. By default returns {prompt_id} immediately; pass wait:true to block until the job completes and return its outputs (images etc.). Unresolvable template names return a clear error with near-matches. template is required.

​

Parameters

​

Examples

{
  "tool": "enqueue_workflow",
  "arguments": {
    "action": "enqueue",
    "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
          ]
        }
      }
    }
  }
}

{
  "tool": "enqueue_workflow",
  "arguments": {
    "action": "template_schema",
    "template": "anima-txt2img"
  }
}

{
  "tool": "enqueue_workflow",
  "arguments": {
    "action": "run_template",
    "template": "anima-txt2img",
    "overrides": {
      "45.text": "a lighthouse in a storm, dramatic sky"
    },
    "wait": true
  }
}

{
  "tool": "enqueue_workflow",
  "arguments": {
    "action": "run_url",
    "url": "https://raw.githubusercontent.com/comfyanonymous/ComfyUI_examples/master/flux/flux_dev_example.json"
  }
}

​

get_system_stats

• action:“stats” — Get system information from the connected ComfyUI server: GPU device(s), total/free VRAM, ComfyUI/Python/PyTorch versions, and OS details. Requires a running ComfyUI server (works against local or remote targets); read-only, takes no parameters. Returns the raw /system_stats JSON. Use to confirm connectivity and check available VRAM before enqueuing large workflows. Errors if the server is unreachable.
• action:“logs” — Get ComfyUI server runtime logs. Useful for debugging execution errors, model loading issues, missing nodes, and Python tracebacks. max_lines tails the end (default 100), keyword filters case-insensitively.
• action:“health” — Pre-flight diagnostic for the connected ComfyUI: one call that aggregates the signals an agent should check before dispatching a batch. Reports ComfyUI version/Python/PyTorch, GPU name + VRAM free/total, system RAM free, queue depth (running + pending), per-category /models populations (catches empty dropdowns from a misconfigured extra_model_paths.yaml), and recent errors from /internal/logs. Read-only — no mutation. Use this when a job fails for an unexpected reason, before a long batch run, or to confirm a remote ComfyUI is healthy. Originally contributed by github.com/joaolvivas.

​

Parameters

​

Examples

{
  "tool": "get_system_stats",
  "arguments": {
    "action": "stats"
  }
}

{
  "tool": "get_system_stats",
  "arguments": {
    "action": "health"
  }
}

{
  "tool": "get_system_stats",
  "arguments": {
    "action": "health",
    "model_categories": [
      "checkpoints",
      "loras"
    ],
    "recent_errors": 5
  }
}

{
  "tool": "get_system_stats",
  "arguments": {
    "action": "logs",
    "keyword": "error",
    "max_lines": 50
  }
}

​

queue

• action:“list” — The job running now plus all pending jobs, each with its prompt_id and position. Read-only; requires a reachable ComfyUI server (works against local or remote —comfyui-url). Omits queued workflow payloads by default to keep output small; set include_workflows:true when you need to inspect or edit the exact pending payload. Use this before action:“cancel” (running), action:“cancel_queued”/action:“clear” (pending), action:“move”, or action:“edit”.
• action:“status” — Check ONE job by its prompt_id (the id returned by enqueue_workflow). Queries the connected ComfyUI server; requires it to be running. Returns JSON with running, pending, and done booleans, plus optional status_str, error details, and execution_stats from ComfyUI history once the job is done. Also returns text_outputs when the workflow contained text-preview nodes (Preview as Text, ShowText, …) — those produce no image file, so this is the ONLY way to read their result; report that text back to the user. Use action:“list” to see the whole queue at once, and get_history for full output filenames.
• action:“get_workflow” — The full workflow payload for one PENDING queue item by prompt_id. Read-only. Does not work for the currently running job because ComfyUI cannot safely edit a job after execution starts.
• action:“move” — Move a PENDING queue item to the front or back by removing it and re-enqueuing its saved workflow payload; position (“front”|“back”) is required. The job receives a NEW prompt_id; the old prompt_id is removed. Running jobs cannot be moved.
• action:“edit” — Edit a PENDING queue item by removing it and re-enqueuing an updated workflow. Provide either a complete replacement workflow or node_inputs patches keyed by node id; position selects where to requeue (default back). The job receives a NEW prompt_id; the old prompt_id is removed. Running jobs cannot be edited.
• action:“cancel” — Stop the CURRENTLY RUNNING job ROBUSTLY. Sends an interrupt, then WAITS and verifies the job actually stopped — ComfyUI only honors interrupts BETWEEN steps, so a long single step (e.g. a high-res video sampler) can ignore a plain cancel. If the interrupt isn’t honored it escalates to freeing VRAM (POST /free) and re-checks; if it STILL won’t die it reports the job as WEDGED and tells you to restart_comfyui (an HTTP cancel cannot kill a stuck step). Set clear_pending:true to also drop ALL pending jobs in the same call — the correct “reset the queue” action, since cancelling alone leaves pending jobs that would run next. The partial result is discarded. With prompt_id given, only interrupts the running job when its prompt_id matches; omit to interrupt whatever is currently running. Use action:“cancel_queued” to remove one specific PENDING job instead.
• action:“cancel_queued” — Remove one specific PENDING job from the queue by prompt_id. Does not affect running jobs.
• action:“clear” — Clear ALL pending jobs from the queue. Does not affect the currently running job.

​

Parameters

​

Example

{
  "tool": "queue",
  "arguments": {
    "action": "list"
  }
}

​

get_history

• action:“list” — Execution history for a ComfyUI prompt: status, timing, cached nodes, and output details (media filenames for get_image action:“get”). Also carries the raw error/traceback. To diagnose WHY a run FAILED or what is missing, prefer action:“diagnose” — it returns the same failure info PLUS missing models (with the file + widget) and missing node types, which this action does not. Use action:“list” when you need the run’s OUTPUTS or timing for a specific prompt_id.
• action:“diagnose” — WHY DID MY RENDER FAIL / WHAT IS MISSING? Explains a failed run in ONE call, without needing a canvas — the headless counterpart to the panel’s panel_get_errors (“why is this red?”), so mobile/remote sessions get the same answer. Returns: the failed node (id, type) with its exception_type + message and a trimmed traceback; missing_models (the exact model file that is not installed and the widget holding it — feed the filename to download_model action:‘search_civitai’, then action:‘download_civitai’ — or action:‘search’ then action:‘download’ — to fix it); missing_node_types (node classes this install lacks — feed to search_custom_nodes, then install_custom_node); and any other per-input validation errors. Call this whenever a run fails, an enqueue is rejected, or the user asks what is missing — instead of guessing from raw logs. With no prompt_id it diagnoses the most recent FAILED run (falling back to the most recent run). Read-only.
• action:“stats” — Statistics from this MCP server’s LOCAL generation-history database (populated as you run workflows; NOT from ComfyUI, and not the same source as action:“list”): total generations, count of unique sampler/scheduler/steps/CFG combos, a per-model-family breakdown, and the most-reused settings. Read-only; works without a running ComfyUI. Returns empty stats until you have generated images. For concrete recommended settings rather than aggregate counts, use action:“suggest”.
• action:“suggest” — Recommend concrete, proven sampler/scheduler/steps/CFG (and denoise/shift/LoRA) settings derived from that same LOCAL generation-history database. Read-only and works without a running ComfyUI. Narrow results by model_family, lora_hash, or a name search; with no filter it returns the top settings across all history. Returns a ranked list with each combo’s reuse count, or a “no history” message until you have generated images. Use this for ready-to-apply values; use action:“stats” for aggregate counts and breakdowns rather than specific suggestions.

​

Parameters

​

Example

{
  "tool": "get_history",
  "arguments": {
    "action": "list"
  }
}

​

calculate

​

Parameters

​

Example

{
  "tool": "calculate",
  "arguments": {
    "spec": "<spec>"
  }
}

​

batch

• action:“submit” — Enqueue a batch. Provide EITHER workflows (array of API-format workflows) OR one workflow plus a sweep (array of flat input-override sets — each set produces one job, applied to every node that already has that input, like create_workflow (action:“modify”)). Reuses the enqueue_workflow path (seeds re-randomized unless disable_random_seed). Returns { batch_id, count, prompt_ids }; the mapping is persisted to disk and stays valid across server restarts.
• action:“status” — Per-job status for batch_id: each prompt_id’s state (pending/running/done/error/unknown) plus rollup counts and all_terminal. Same status source as queue (action:“status”).
• action:“output” — Collected outputs for the batch’s COMPLETED jobs: for each done prompt_id, the raw ComfyUI history outputs (node id → images/videos/audio filenames, same data get_history reports — feed filenames to get_image action:“get”). Jobs still pending/running are listed with their state; errored jobs carry the error message. Safe to call before the batch finishes.
• action:“wait” — Block until every job is terminal (done or error) or timeout_s elapses, then return the same rollup as action:“status” plus timed_out/waited_s. Default timeout 300s, hard cap 600s — it can never hang; if timed_out is true, call it again or poll action:“status”. Batch ids are durable — they survive server restarts.

​

Parameters

​

Example

{
  "tool": "batch",
  "arguments": {
    "action": "submit"
  }
}