comfyui-mcp

upload_image

Upload local media to ComfyUI's input directory or stage existing outputs as inputs for use in nodes.

Instructions

Put a file where ComfyUI (or cloud storage) can read it. Driven by the action parameter:

action:"image" — Upload a local image file to the connected ComfyUI's input/ directory via the HTTP /upload/image endpoint so it can be referenced in LoadImage nodes. Works for both local and remote ComfyUI. Nested filenames that LoadImage does not enumerate are re-registered at the input root; the returned filename is the one a LoadImage combo can select.
action:"video" — Upload a local video file (.mp4, .mov, .webm, .avi, .mkv, .m4v) to the connected ComfyUI's input/ directory via the HTTP /upload/image endpoint for use in video-loading nodes such as VHS_LoadVideo (ComfyUI-VideoHelperSuite). Works for both local and remote ComfyUI. Returns the stored filename.
action:"audio" — Upload a local audio file (.wav, .mp3, .flac, .ogg, .m4a, .aac) to the connected ComfyUI's input/ directory via the HTTP /upload/image endpoint for use in audio-conditioned workflows (e.g. LoadAudio). Works for both local and remote ComfyUI. Returns the stored filename.
action:"stage" — Stage an EXISTING ComfyUI output (or temp/preview) as an INPUT so the next stage's loader (LoadImage / VHS_LoadVideo / LoadAudio) can read it. This is the CORRECT way to chain a multi-stage pipeline (e.g. Krea2 image → LTX video → WAN extend): it fetches the output's bytes from the server via /view and re-registers them as an input via /upload/image — the same endpoints get_image and the uploads above use. Because it goes entirely through the server API, it works even when ComfyUI was launched with a CUSTOM input/output directory. Do NOT instead copy the output file or guess a filesystem input/ path — the server's input dir may be custom and it will reject the file ("Invalid image file"), wasting the render. Pass an existing output reference ({ filename, subfolder?, type? }); the media kind (image/video/audio) is inferred from the extension unless you set kind. Nested video as_filename values are staged at the input root because VHS_LoadVideo lists only top-level files. Returns { filename, subfolder, type: "input", kind } — drop filename into LoadImage / VHS_LoadVideo / LoadAudio combo widgets. VHS_LoadVideoPath needs the returned filesystem path, not that combo filename ("Invalid file path" otherwise).
action:"output" — Upload a generated ComfyUI output to CLOUD storage (this is the only action that sends bytes off the machine). Source can be asset_id or a local path under COMFYUI_PATH/output. Destination can be S3, Azure Blob, HTTP PUT, or HuggingFace via the hf CLI.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	No	action:"stage" — force the media kind instead of inferring it from the file extension.
`path`	No	action:"output" — path to a generated output under COMFYUI_PATH/output. Provide exactly one of asset_id or path.
`type`	No	action:"stage" — source directory the asset lives in: output (default) or temp (previews).
`action`	Yes	What to upload and where. "image"/"video"/"audio" send a LOCAL file (`source_path`) to ComfyUI's input/ directory; "stage" re-registers an EXISTING server-side output (`filename`) as an input; "output" ships a generated output to cloud storage (`destination`).
`asset_id`	No	action:"output" — registered asset id from a completed job. Provide exactly one of asset_id or path.
`filename`	No	Two meanings, one per action. actions "image"/"video"/"audio" — OPTIONAL override for the filename in ComfyUI's input/ directory (auto-detected from source_path if omitted). A path prefix (e.g. assets/clip.mp4) places the upload in that SUBFOLDER of input/ — ".." is refused — and the returned filename reference includes the subfolder when the loader enumerates it. action:"image" verifies the name against LoadImage /object_info and, if a nested path is stored but not listed, returns a verified root filename instead. action:"stage" — REQUIRED filename of the EXISTING output/temp asset to re-register (from get_history or get_image action:"list_outputs"), e.g. LTX_video_00001.mp4; its destination name override is `as_filename`, not this field.
`subfolder`	No	action:"stage" — subfolder the source asset currently lives in, if any.
`as_filename`	No	action:"stage" — override the filename it is registered under in the input/ directory (defaults to the source filename).
`destination`	No	action:"output" — REQUIRED. Exactly one upload destination.
`source_path`	No	Absolute path to the local file to upload. REQUIRED for actions "image", "video" and "audio".

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 30, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses endpoints used, local-vs-remote compatibility, custom input/output directory behavior, '..' refusal, nested filename re-registration, extension support, and which action sends bytes off the machine. It also warns about the specific failure mode 'Invalid image file' when bypassing the server API. This is unusually transparent for a mutation/upload tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is appropriately front-loaded and structured as one general purpose statement followed by action-specific bullets, which makes a five-action tool navigable. However, it repeats identical phrases such as 'Works for both local and remote ComfyUI' and 'via the HTTP /upload/image endpoint' across multiple action bullets. That repetition is minor but prevents a perfect conciseness score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, absence of annotations, nested destination object, and lack of an output schema, the description is complete enough for correct invocation. It explains the critical return shape for action:'stage' and the returned stored filename for local uploads, and it covers the distinct behavior of action:'output' as the only cloud-egress path. Remaining omissions, such as cloud authentication details, are not essential to selecting or calling the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters such as action, filename, as_filename, kind, source_path, and destination. The description largely expands on the same action meanings with workflow context rather than adding parameter syntax or constraints beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting for parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Put a file where ComfyUI (or cloud storage) can read it,' then enumerates each action with its exact upload/stage/output behavior. It distinguishes the tool's upload role from source-generation or retrieval siblings by tying actions to concrete loader nodes like LoadImage, VHS_LoadVideo, and LoadAudio. An agent can tell what the tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly covers when to use each action and when not to use certain approaches, especially for action:'stage': it is named as the CORRECT way to chain multi-stage pipelines and the description directly warns against copying output files or guessing filesystem input paths. It also routes source discovery through get_history or get_image action:'list_outputs'. This is strong when/when-not guidance with concrete alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upload_image

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools