Discover the connected instance, supervisor, paths, ports, and versions.

For a local Comfy Desktop endpoint, this correlates API argv, the listening PID/process tree, and Desktop's installation registry. It never starts, stops, or changes the instance.

Get ComfyUI system stats: OS, GPU, VRAM, version info. Returns structured SystemStats.

Get detailed GPU info: VRAM total/free/used, torch version, device names.

List enabled ComfyUI features (v0.17+).

List all installed ComfyUI custom nodes and extensions.

Safely restart the selected local instance through Manager V2.

First call comfy_instance_doctor and pass back either its instance_id or listener PID. The selector is checked immediately before the mutation. Desktop/Manager V2 is used when available; ComfyPilot never falls back to launching a competing server on port 8188.

Unload models and/or free VRAM memory.

Args: unload_models: Unload all loaded models from VRAM free_memory: Free cached memory allocations

List models in a folder with pagination. Returns structured ModelList.

Args: folder: Model folder name (e.g., "checkpoints", "diffusion_models", "loras", "vae", "text_encoders"). Call comfy_list_model_folders to see every folder the connected ComfyUI actually exposes. limit: Maximum number of results per page. offset: Starting position for pagination. include_non_model_files: Include caches, source files, lock metadata, archives, and unknown extensions returned by custom folders.

Get node schema for a model-related node type.

Returns the node's input/output definition from ComfyUI's object_info, not model file metadata.

Args: node_type: The node class type to inspect (e.g., "CheckpointLoaderSimple")

List every model-folder name the connected ComfyUI exposes.

Uses ComfyUI's /models endpoint to discover folders live. Reports the data source ("live" vs "fallback") so callers know whether the list reflects their actual install.

Search for models by name across folders.

By default searches every folder ComfyUI exposes (discovered live via /models). Pass folders=["checkpoints", "loras"] to narrow.

Args: query: Case-insensitive substring match against filenames. Empty string returns every model in every folder (useful for a full inventory). folders: Explicit folder list to restrict the search. None means search all discovered folders. include_non_model_files: Include cache locks, Python sources, wheels, archives, and unknown file types. Default False.

Re-fetch the model list from ComfyUI across every known folder.

Note: this re-reads ComfyUI's current model cache. It does NOT trigger a server-side filesystem rescan. Returns per-folder counts so the caller can see where the installed weights live.

Queue a workflow for execution. Returns structured QueueAck.

Args: workflow: Workflow dict to queue front: If True, insert at front of queue instead of back workflow_id: Optional stable workflow UUID for ComfyUI job metadata workflow_version_id: Optional workflow-version UUID partial_execution_targets: Optional output node IDs to execute extra_data: Optional metadata to attach to the queued prompt

Get current queue state including running and pending prompts.

Cancel a running or queued prompt by ID.

Args: prompt_id: The prompt ID to cancel

List ComfyUI jobs using the v0.20+ canonical jobs API.

Args: status: Optional job state filter workflow_id: Optional workflow UUID filter sort_by: Optional server-supported sort field sort_order: asc or desc limit: Maximum records to return (1-1000) offset: Offset pagination when after is omitted after: Cursor pagination token when supported

Get a full modern job record, with a legacy history fallback.

Cancel multiple running or queued jobs (v0.26+, with legacy fallback).

Interrupt the currently executing prompt.

Clear all pending prompts from the queue. Destructive.

Args: confirm: If False, the tool asks for explicit confirmation via elicitation before proceeding. Pass True to skip the prompt.

Validate a workflow with a 6-pass check. Returns structured ValidationReport.

Passes: schema -> catalog -> graph -> anti_cycle -> environment -> execution_risk. A pre-pass detects ComfyUI editor-format (top-level nodes/links arrays) and short-circuits with a specific re-export instruction.

Export/serialize a workflow to JSON string.

Simply returns the workflow formatted nicely as JSON string.

Parse a JSON string into a workflow dict.

Parses the JSON string and validates basic structure. Returns the parsed workflow dict as JSON.

List all available node types with pagination.

Args: limit: Maximum number of results per page offset: Starting position for pagination

Returns: JSON with node_types list, total_count, has_more, next_offset

Get detailed normalized info about a specific node type.

Returns a NodeSchema-shaped payload: class_type, category, description, inputs (with name/type/required/constraints/is_link_target per input), outputs, is_output_node, schema_version ('v1' or 'v3').

Args: node_type: The node type name to get info for

Search for nodes by name (case-insensitive substring match).

Args: query: Search query string limit: Maximum number of results to return

Returns: JSON with matches list and total match count

Get all node categories.

Returns: JSON with sorted list of categories and their node counts

List available embeddings.

Returns: JSON with embeddings list and count

Get widget/input details for a node type (normalized, V1/V3 transparent).

Returns: node_type: class name inputs: list of {name, type_name, required, constraints, is_link_target} widget_inputs: subset of inputs that are widgets (is_link_target=False) link_inputs: subset of inputs that expect links from other nodes

Args: node_type: The node type name to inspect

Download an output image from ComfyUI and return it as an image content block.

Args: filename: Image filename (e.g. "ComfyUI_00001_.png") subfolder: Optional subfolder within the output directory

Upload an image to ComfyUI.

Args: image_data: Base64-encoded image data filename: Destination filename subfolder: Optional subfolder within the input directory overwrite: Whether to overwrite an existing file with the same name

List output images from history with a local filesystem fallback.

Args: subfolder: Optional subfolder to filter by limit: Maximum number of filenames to return

Get lightweight metadata for multiple output images.

By default this is a pure metadata lookup - no image bytes cross the wire. Each entry contains {filename, subfolder, type, url}. Pass include_size=True to also populate size_bytes, which requires downloading each image. That path should only be used for short lists.

Args: filenames: List of image filenames to query. subfolder: Optional subfolder within the output directory. include_size: If True, fetch each image to populate size_bytes. Default False - the tool advertised itself as "metadata only" but the pre-1.5.3 implementation downloaded every full body.

Get the URL to view an image on the ComfyUI server.

Args: filename: Image filename subfolder: Optional subfolder image_type: Image type (output, input, temp)

Get execution history with pagination.

Args: limit: Maximum number of entries to return (default 20)

Returns: JSON with entries list and total count

Get result of a specific prompt execution. Returns structured RunResult.

Args: prompt_id: The ID of the prompt execution to retrieve

Delete a specific history entry. Destructive.

Args: prompt_id: The ID of the prompt execution to delete confirm: If False, the tool asks for explicit confirmation via elicitation before proceeding. Pass True to skip the prompt.

Clear ALL execution history. Destructive and cannot be undone.

Args: confirm: If False, the tool asks for explicit confirmation via elicitation before proceeding. Pass True to skip the prompt.

Search history for prompts containing specific node types.

Args: query: Search term (case-insensitive substring match on node class_type) limit: Maximum number of matches to return (default 20)

Returns: JSON with matching history entries

Poll EventManager for a prompt's execution progress. Returns structured WatchProgressFrame.

Args: prompt_id: The prompt ID to watch

Register interest in an event type.

Args: event_type: The event type to subscribe to (e.g., 'progress', 'error', 'complete')

Returns: JSON confirming subscription

Remove subscription to an event type.

Args: event_type: The event type to unsubscribe from

Returns: JSON confirming removal

Drain buffered events from EventManager.

Args: event_type: Optional filter by event type limit: Maximum number of events to return (default 100)

Returns: JSON with events list and count

One-shot snapshot of system dynamics (queue + recent events + active jobs).

Returns structured DynamicsReport with queue counts, recent event types, and active job summary.

One-shot status overview (queue + GPU + execution state + events).

Returns: Combined status JSON with queue info, system stats, and event health

Create a snapshot of the current workflow state.

Args: workflow: The workflow dictionary to snapshot name: Optional name for the snapshot

Returns: JSON with snapshot id, name, timestamp, and node_count

List workflow snapshots (newest first). Returns structured SnapshotList.

Args: limit: Maximum number of snapshots to return (default 20)

Diff two snapshots or a snapshot vs current workflow.

Args: id_a: First snapshot ID id_b: Optional second snapshot ID current_workflow: Optional current workflow to diff against

Returns: JSON with added_nodes, removed_nodes, modified_nodes, total_changes

Get a snapshot's workflow data for restoration.

Args: snapshot_id: The snapshot ID to restore

Returns: JSON with full snapshot data including workflow

Delete a snapshot. Destructive.

Args: snapshot_id: The snapshot ID to delete confirm: If False, the tool asks for explicit confirmation via elicitation before proceeding. Pass True to skip the prompt.

Toggle automatic snapshot creation on workflow execution.

Args: enabled: Whether to enable auto-snapshots

Returns: JSON confirming the new auto_snapshot flag state

Save a workflow as a reusable technique.

Args: workflow: The workflow dictionary to save name: Name for the technique description: Optional description tags: Optional list of tags for categorization

Search workflow techniques by text query and/or tags.

Args: query: Text to search in name, description, and tags tags: Optional list of tags to filter by limit: Maximum number of results to return (default 20)

List all saved workflow techniques (newest first). Returns structured TechniqueList.

Args: limit: Maximum number of techniques to return (default 50)

Get the full technique data including workflow for re-use.

Args: technique_id: The technique ID to retrieve

Set favorite status and/or rating for a technique.

Args: technique_id: The technique ID to update favorite: Whether to mark as favorite (default True) rating: Rating from 0-5, or -1 to leave unchanged (default -1)

Check current GPU VRAM usage. Returns structured VRAMStatus with per-device detail.

Update VRAMGuard safety thresholds.

Args: warn_pct: VRAM percentage to trigger warn status (default 80.0) block_pct: VRAM percentage to trigger critical/block status (default 95.0) max_queue: Maximum queue depth before blocking (default 10) timeout: Job timeout in seconds (default 300)

Returns: JSON with updated threshold values

Check for stuck jobs, OOM patterns, and other instability signals.

Returns: JSON with stable flag, issues list, and queue counts

Emergency stop: interrupt current job, clear queue, and free VRAM. Destructive.

WARNING: This is destructive - it will cancel all running and pending jobs.

Args: confirm: If False, the tool asks for explicit confirmation via elicitation before proceeding. Pass True to skip the prompt (useful when firing from automated safety checks).

Pre-flight safety check before queueing a prompt.

Checks VRAM headroom and current queue depth.

Returns: JSON with safe_to_queue flag, VRAM status, queue counts, and any issues

Build a ComfyUI workflow for an intent, routed to the detected model family.

The checkpoint family is detected from params['checkpoint'] (or auto-detected from the first installed checkpoint if ctx is provided) and dispatched to a family-specific builder. SD 1.5 is the fallback when the family can't be determined.

Intents by family: SD 1.5: txt2img, img2img, upscale, inpaint, controlnet SDXL / SD 3.5: txt2img Flux 2 / Qwen: txt2img Wan 2.2: txt2video, img2video LTX-2: txt2video HunyuanVideo: txt2video, img2video Hunyuan3D: image2_3d ACE-Step: txt2music

Args: template: Intent name (e.g. 'txt2img', 'txt2video', 'image2_3d', 'txt2music'). params: Optional param overrides. If 'checkpoint' is set, family routing uses it; otherwise the first installed checkpoint is auto-detected.

Add a node to a workflow.

Args: workflow: The workflow dictionary to modify node_id: ID for the new node (string, e.g. "8") class_type: ComfyUI node class type inputs: Optional input values for the node

Connect two nodes in a workflow.

Args: workflow: The workflow dictionary source_node: ID of the source node source_output: Output index on the source node target_node: ID of the target node target_input: Input name on the target node

Set a widget value on a workflow node.

Args: workflow: The workflow dictionary node_id: ID of the node to modify widget_name: Name of the widget/input to set value: Value to set

Apply a workflow template and return the resulting workflow.

Convenience alias for comfy_build_workflow.

Args: template: Template name (txt2img, img2img, upscale, inpaint, controlnet) params: Optional parameters to override template defaults

Download an image from ComfyUI and save to local disk atomically with a sidecar manifest.

Args: filename: The image filename in ComfyUI outputs subfolder: Optional subfolder in ComfyUI outputs output_dir: Optional override for output directory (default: COMFY_OUTPUT_DIR env var) prompt_id: Optional prompt_id to enrich the manifest with history metadata

Download image and save for TouchDesigner consumption atomically with sidecar manifest.

Args: filename: The image filename in ComfyUI outputs subfolder: Optional subfolder in ComfyUI outputs prompt_id: Optional prompt_id to enrich the manifest with history metadata

Download image and save for Blender consumption atomically with sidecar manifest.

Args: filename: The image filename in ComfyUI outputs subfolder: Optional subfolder in ComfyUI outputs prompt_id: Optional prompt_id to enrich the manifest with history metadata

List configured output destinations and their paths.

List subgraph blueprints from the configured sources.

Sources:

• "all" (default): user + bundled + native (everything available).

• "user": only the user-published store (COMFY_BLUEPRINT_DIR).

• "bundled": only the bundled examples shipping with ComfyPilot.

• "native": only the global subgraphs ComfyUI itself publishes.

User blueprints shadow bundled ones when names collide. Native entries are tagged with source: "native" so the caller can distinguish them from ComfyPilot-managed blueprints.

Materialize a blueprint into a workflow dict.

Args: name: Blueprint name (from comfy_list_blueprints). inputs: Optional {node_id: {input_name: value}} overrides applied to the blueprint's nodes when inserted.

Save a set of nodes as a reusable blueprint.

Args: name: Blueprint name (must not contain '/' or '..'). nodes: Dict of {node_id: node_spec} forming the blueprint graph. description: Free-text description for discoverability. tags: Optional tags for search/filter.

Render an API-format workflow as a Mermaid flowchart.

The returned string is valid Mermaid source (flowchart TD). Paste into any Mermaid renderer (GitHub, mermaid.ink, mermaid-cli).

Args: workflow: API-format {node_id: {class_type, inputs}} dict. title: Optional title string inserted as a diagram comment.

Extract a workflow from a ComfyUI-saved PNG's tEXt metadata.

ComfyUI embeds the workflow JSON in the PNG on save:

• 'prompt' chunk: API format (directly queueable)

• 'workflow' chunk: UI format (with positions, widgets)

This tool prefers 'prompt' and falls back to 'workflow'. Returns {format: 'api' | 'ui' | 'none', workflow: dict, path: str}.

Args: png_path: Absolute path to the PNG file.

Enqueue N copies of workflow, each with a different value for one widget.

Useful for seed sweeps, CFG sweeps, step sweeps, denoise sweeps. Every queued prompt is also registered with the job tracker so the returned prompt_ids can be fed into comfy_watch_progress.

Args: workflow: Base API-format workflow. node_id: Node id whose input to vary (e.g. "5" for KSampler). param: Input name to vary (e.g. "seed", "cfg", "steps"). values: List of values to substitute. Each produces one queued prompt.

N-dimensional parameter sweep over a Cartesian product of axes.

Where comfy_sweep varies one widget across a list, this enqueues every combination across multiple axes. E.g. seed x cfg x steps with 3 values on each axis produces 27 queued prompts.

Args: workflow: Base API-format workflow. axes: Mapping of 'node_id.param' -> list of values. At least 1 axis; order is preserved for the returned grid_shape. max_combinations: Hard cap on total queued prompts. Reject the call when the Cartesian product would exceed this. Default 64.

Returns: JSON with prompt_ids list (length = product of axis sizes), the grid_shape (e.g. [3, 3, 3] for 3x3x3), and a per-prompt assignment map so the caller can label each output.

Search a public model hub for models matching a query.

Args: query: Free-text search, e.g. "flux2 klein" or "sdxl anime". source: "huggingface" or "civitai". Default huggingface. limit: Max results (1-50). Default 10.

List partner-API custom nodes installed on the connected ComfyUI.

Intersects the installed extensions list (from ComfyUI's /extensions endpoint) with ComfyPilot's curated KNOWN_PARTNER_APIS catalog. Useful before suggesting workflows that depend on cloud-backed nodes - tells the agent which vendors (Veo, Kling, Seedream, GPT-Image, etc.) are actually wired up on this server.

Returns: JSON with installed (list of detected partners) and available (full catalog) so the agent can suggest installs when needed.

Extract the controllability / dependency surface of a workflow.

Returns a structured summary of every controllable widget input across all nodes, every model the workflow depends on (loader nodes), every embedding reference embedded in text inputs, and every output node. Lets an agent decide what to parameterise without walking the graph node-by-node.

Args: workflow: API-format workflow dict. summary_only: If True, return just the high-level counts/flags (parameter_count, has_negative_prompt, has_seed, model_count, node_count) without the per-parameter list.

Retrieve execution logs / error traceback for a specific prompt.

ComfyUI's /history/{prompt_id} response carries a status.messages array with per-step execution events and status.exec_info.errors with traceback strings on failure. This tool extracts just the log-relevant fields (status, errors, per-node traceback, completed nodes) so the caller doesn't have to walk the full response.

Args: prompt_id: Prompt ID returned by comfy_queue_prompt.

Enumerate custom (non-stock) node class types in a workflow.

Workflow JSON is arbitrary code - custom nodes run Python on the ComfyUI server. This tool surfaces which class_types are NOT in the set of ComfyUI core / first-party node patterns, so an agent can warn the user (or refuse to auto-queue) before submitting a workflow from an untrusted source.

Returns a JSON report with trust_level (stock | mixed | fully_custom), the stock + custom class lists, and per-warning strings.

Inspect connected GPU and recommend local vs Comfy Cloud routing.

Returns one of three verdicts:

• ok - run everything locally (>=8 GB discrete VRAM or >=32 GB unified Apple Silicon)

• marginal - SD 1.5 OK, SDXL tight, Flux/video unlikely. Cloud recommended for heavy workloads.

• cloud - no usable GPU, <6 GB VRAM, <16 GB unified, Intel Mac, or Rosetta Python. Route to Comfy Cloud.

Also reports the appropriate comfy-cli install flag (--nvidia, --amd, --m-series, --cpu) so the caller can pass it to comfy_install_node / comfy_launch_server flows.

Recommend an HTTP timeout for a workflow based on its output nodes.

Default ComfyPilot timeout is 300 s. Video / audio / 3D / training workflows routinely exceed that. This tool walks the workflow, finds every output-producing node, and returns the largest matching timeout plus the node that drove the decision.

Args: workflow: API-format workflow dict.

Start an explicitly selected ComfyUI workspace via comfy-cli.

This tool has no implicit 8188 fallback. workspace and port must be explicit, and a healthy connected endpoint blocks launch unless the caller deliberately sets allow_parallel=True. This prevents a Desktop install on port 8000 from accidentally gaining a competing CLI process.

Args: background: Run as a detached daemon (default True). False blocks until the server exits. port: Explicit port for ComfyUI's HTTP server. host: Host to bind on. Default 127.0.0.1; use 0.0.0.0 for LAN access. workspace: Optional --workspace path passed to comfy-cli (selects which ComfyUI install to launch when multiple are present). extra_args: Additional argv to forward verbatim after -- (e.g. ['--listen', '0.0.0.0', '--cpu']). allow_parallel: Permit launch while the currently selected endpoint is already healthy. Default False. confirm: Explicitly confirm this process-start mutation.

Stop an explicitly selected non-Desktop ComfyUI server via comfy-cli.

Desktop-supervised instances are never handed to comfy stop because that can target a different comfy-cli workspace. Use Comfy Desktop itself for a full stop, or comfy_restart for Manager V2 restart.

Args: workspace: Optional --workspace path passed to comfy-cli (selects which ComfyUI install to stop when multiple are present). expected_instance_id: Optional Desktop instance selector from comfy_instance_doctor. expected_pid: Optional listener PID selector. confirm: Explicit confirmation; otherwise MCP elicitation is used.

Returns: JSON with one of three shapes: - {status: "stopped", comfy_cli_returncode: 0, stdout, stderr} on successful shutdown. - {status: "failed", comfy_cli_returncode: N, stdout, stderr} when the binary is present but the call exits non-zero (most commonly: no server was running to stop). - {error: "...install hints..."} when comfy-cli is not on PATH.

Install a custom node via comfy node install <name>.

Uses Comfy Manager under the hood. Name format is typically the GitHub repo's slug (e.g. 'comfyui-impact-pack', 'comfyui-controlnet-aux', 'comfyui-animatediff-evolved').

Args: name: Custom-node package name. workspace: Explicit comfy-cli workspace path. confirm: Explicitly confirm package installation.

List custom-node packages, preferring the live Manager V2 API.

Manager V2 is dramatically faster and, unlike comfy-cli, is guaranteed to describe the connected running installation. comfy-cli remains a compatibility fallback when no Context/API is available.

Args: workspace: Optional --workspace path passed to comfy-cli. mode: Manager inventory mode (imported by default). prefer_manager_api: Try /v2/customnode/installed first.

Returns: JSON with one of three shapes: - {status: "ok", raw_lines: [...], line_count: N} when the listing succeeded. line_count==0 means no custom nodes are installed (or only stock ComfyUI is present). - {status: "failed", comfy_cli_returncode, stderr} when the binary is present but the call exits non-zero. - {error: "...install hints..."} when comfy-cli is not on PATH.

Download a model via comfy model download --url ... --relative-path models/<folder>.

Args: url: Direct download URL (HuggingFace, CivitAI, etc.). For CivitAI links, also pass civitai_api_token. folder: Subfolder under models/. Common values: checkpoints, loras, vae, diffusion_models, text_encoders, controlnet, upscale_models. civitai_api_token: Optional CivitAI API token for gated downloads. workspace: Optional --workspace path. confirm: Explicitly confirm the network download and filesystem write.

Auto-install every custom-node package the workflow references.

Wraps comfy node install-deps --workflow=<file>. The workflow is serialised to a temp file (in API format), passed to comfy-cli, and the temp file is removed after. Long-running call (each missing package downloads + installs): default timeout 600 s.

Args: workflow: API-format workflow dict. workspace: Optional --workspace path passed to comfy-cli.

Upload local images, inject as workflow inputs, then queue.

Combines the three-step img2img / inpaint flow (upload + patch + queue) into one tool call. Each entry in inputs is a (label, local_path) pair: the file is uploaded to ComfyUI's input directory and the workflow's matching input widget is set to the uploaded filename.

Args: workflow: API-format workflow dict (will be deep-copied before patching - the caller's dict is not mutated). inputs: Mapping of label -> local file path. Labels may be "node_id.input_name" for explicit targeting or just "input_name" to patch every matching widget. front: Insert at the front of the queue (default False).

Returns: QueueAck (typed) with prompt_id, queue_number, plus an auto_snapshot field listing the upload mapping that was applied.

Replace seed sentinels (-1) with fresh random uint32 values.

By default, only widgets currently set to -1 are randomised; this lets a caller "opt in" by writing -1 for the seeds they want fresh while pinning the others to specific values. Set force=True to randomise every seed widget in the workflow regardless of its current value.

Uses secrets.randbelow(2**32) for cryptographic-grade randomness - avoids the seeded global random module so concurrent randomisation calls don't share a stream.

Args: workflow: API-format workflow dict (deep-copied; caller's dict stays unchanged). force: Randomise every seed widget regardless of current value.

Returns: JSON with workflow (patched copy) and assignments mapping node_id.field -> new_seed.

List image, video, audio, mesh, or other output artifacts.

History is merged with the local output filesystem for loopback instances, so outputs remain discoverable after ComfyUI history is reset. Paths are constrained to the output root and filesystem symlinks cannot escape it.

Get safe metadata (and optionally base64 bytes) for one output file.

relative_path is always resolved beneath the connected local instance's argv-derived output directory. Absolute paths, .. and symlink escapes are rejected. Inline bytes are opt-in and capped at 25 MiB.

Inspect Env Manager runtime, node environments, and workers.

Each endpoint is independent: a broken /env-manager/runtime response is reported without hiding working environment/worker data. By default the often very large environment list is reduced to configured or materialized entries.

List active comfy-env subprocess workers, PIDs, Python, and generation.