comfyui-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@comfyui-mcp-server Run a batch of 20 randomized logo generations with auto LoRA stacks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
comfyui-mcp-server
An MCP server that gives an agent direct control of a running ComfyUI instance: submit workflows, run randomised batch discovery, shape LoRA stacks, and read back the provenance of every image produced.
Built for iterative aesthetic discovery -- generate wide, curate narrow, and keep a verifiable record of the parameters that produced the survivors.
Not affiliated with
joenorton/comfyui-mcp-serveror any other project of a similar name. This is an independent implementation (@retiform-labs), and its tool surface is specific to the workflow templates it ships.
What it does
Thirteen tools, split into four groups:
Lifecycle -- system_check · start_comfyui · stop_comfyui · get_comfyui_status
Generation -- generate_image · generate_ipadapter · get_job_status
Batch -- batch_generate · batch_generate_ipadapter
Hardware -- list_models · download_model · get_vram_usage · emergency_cleanup
Randomised batch discovery
The point of the batch tools is divergence, not repetition. Pass a randomize
spec and each job in the batch draws its own parameters:
{
"randomize": {
"seed": "random", // fresh seed per job, deduplicated
"sampler": "random", // from a curated safe pool
"cfg_scale": [5.0, 9.0], // uniform in range
"loras": {"mode": "auto", "count": [1, 3], "weight": [0.25, 0.7]}
}
}Ranges are 2-element lists [min, max]. A dict like {"min": 1, "max": 5} is
rejected with an error rather than silently sent to the workflow as a literal --
that mistake is easy to make and produces a batch where nothing varies.
LoRA stack shape matters more than the sum
Two LoRAs at equal weight average two aesthetics into a muddle. A stack generally wants one dominant adapter and one supporting it:
dominant:
0.55--0.77supporting:
0.25--0.40optional style pin:
~0.45
A total weight around 1.3 is normal and is not a ceiling -- well-shaped
stacks run above it and produce the best results.
Related MCP server: ComfyUI MCP Hub
Tool reference
Every tool returns JSON. generate_* and batch_* are asynchronous: they
queue work and return a job id immediately, because a diffusion run takes far
longer than any sane request timeout. Poll get_job_status for the result.
Lifecycle
system_check()
Reports GPU name, driver version, total and free VRAM, and whether ComfyUI is
responding. Reads nvidia-smi, so it sees the whole GPU -- including memory
held by ComfyUI, which a torch call inside this process never could.
// no arguments
{"gpu": "NVIDIA GeForce RTX 4090", "vram_total_mb": 24564,
"vram_free_mb": 3703, "comfyui_running": true, "comfyui_version": "0.x"}start_comfyui(lowvram=True, fp16=True, port=8188)
Launches ComfyUI if it is not already running. lowvram is the safe default for
cards under ~8 GB.
{"success": true, "pid": 41233, "port": 8188, "already_running": false}stop_comfyui(force=False)
Stops the ComfyUI process. force=True sends SIGKILL when a normal shutdown
hangs.
get_comfyui_status()
Lightweight liveness check -- cheaper than system_check because it never shells
out to the driver.
{"running": true, "port": 8188, "queue_remaining": 0}Generation
generate_image(...)
Text-to-image through the packaged SDXL workflow.
Parameter | Default | Notes |
| required | What to generate |
|
| What to avoid |
|
| A textual-inversion embedding name |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| One LoRA filename from |
|
| |
|
| Several at once: |
|
| Omit for a random seed |
|
| PNG carries provenance metadata |
{"prompt": "a geometric fox mark, single flat ink colour, high contrast",
"width": 1024, "height": 1024, "steps": 30, "seed": 1777732588}
// -> {"job_id": "a3f9...", "status": "queued", "params": {...}}generate_ipadapter(...)
Reference-guided generation. Feeds 1--4 images into the model to steer style, composition or content.
Parameter | Default | Notes |
| required | |
| required | 1--4 filenames from |
|
| How hard the references pull |
|
| Also |
|
| Fraction of sampling the adapter applies over |
|
| |
|
| |
|
| |
|
| |
|
| |
| env default | Override the CLIP vision tower |
| env default | Override the IP-Adapter weight |
{"prompt": "the reference mark, redrawn as a woodcut",
"reference_images": ["ref-a.png", "ref-b.png"],
"reference_weight": 0.65, "weight_type": "style transfer"}Reference images must already exist in ComfyUI's
input/directory. This tool does not upload files; it names them. A missing file is a raised error, not a silent no-op.
get_job_status(job_id)
Polls a queued job. Returns queued, running, completed or failed, and on
completion the output image filenames with their provenance payload.
{"job_id": "a3f9...", "status": "completed",
"images": [{"filename": "image_output_00042_.png", "subfolder": "", "type": "output"}],
"params": {"seed": 1777732588, "sampler": "euler_ancestral", "steps": 30, ...}}Batch
batch_generate(prompts, shared_params=None, randomize=None, deduplicate_seeds=True, priority="normal", keep_loaded=False)
Queues one job per prompt, optionally randomising parameters across the batch.
prompts-- a list of positive prompt strings, one per job.shared_params-- static parameters applied to every job (accepts an object or a JSON string).randomize-- per-job draws; overridesshared_paramswhere it names the same key.deduplicate_seeds-- guarantees no two jobs share a seed.keep_loaded-- leave the model resident after the batch. See VRAM behaviour.
{"prompts": ["a fox mark", "an owl mark", "a wave mark"],
"shared_params": {"width": 1024, "height": 1024, "steps": 24},
"randomize": {"seed": "random", "cfg_scale": [5.0, 9.0],
"loras": {"mode": "auto", "count": [1, 2], "weight": [0.25, 0.7]}}}Randomisation spec forms:
Form | Meaning |
| Draw from a curated safe pool |
| Draw from the full pool, including values that often break |
| Uniform draw in a numeric range |
| LoRA stack selection |
scalar (e.g. | Fixed at that value |
batch_generate_ipadapter(prompts, reference_images, ...)
The reference-guided equivalent, taking the same batch arguments plus the
IP-Adapter parameters from generate_ipadapter.
Hardware
list_models(model_type="all")
Lists what is actually on disk, with sizes. model_type filters to one of
unet, clip, vae, loras, ipadapter, clip_vision.
{"model_type": "loras"}
// -> [{"name": "copperplate_v2.safetensors", "type": "loras",
// "size_mb": 172.4, "format": "safetensors"}]download_model(url, model_type, filename=None, expected_sha256=None, token=None)
Downloads from a Civitai-style URL. Writes atomically -- a partial download never
lands under the final name -- and sanitises filename to a single path
component, so a crafted URL cannot write outside the model directory.
{"url": "https://civitai.com/api/download/models/12345",
"model_type": "loras", "filename": "copperplate_v2.safetensors"}get_vram_usage()
Current GPU memory as the driver reports it. Reads nvidia-smi rather than this
process's CUDA context, which never allocates and would always read zero.
{"used_mb": 9216, "total_mb": 24564, "free_mb": 15348}emergency_cleanup(restart_comfyui=False)
Frees GPU memory by asking ComfyUI to unload its models, then re-reads the driver to report what was actually released. Useful before handing the GPU to a non-ComfyUI job.
{"models_unloaded": ["sdxl-base"], "vram_freed_mb": 9001,
"vram_before_mb": 9216, "vram_after_mb": 215}
restart_comfyui=Trueis the heavier option: it stops and restarts the server. Use it when a normal unload does not recover the memory.
Requirements
Python 3.11+
A running ComfyUI instance with the nodes your workflows use (
UnetLoaderGGUFand the IP-Adapter nodes, for the shipped templates)nvidia-smionPATHfor the VRAM tools (NVIDIA drivers)Models, LoRAs, embeddings and CLIP/VAE weights are NOT included. Source them yourself and place them where ComfyUI expects them. This repository ships code, workflow templates and instructions -- never another party's licensed artifacts.
The IP-Adapter templates reference these filenames; substitute your own:
Node | Default filename | Override with |
|
|
|
|
|
|
These are defaults, not requirements. If your install uses a different CLIP
vision tower or IP-Adapter weight, pass the filename to generate_ipadapter or
set the environment variable -- no code change, and no failure to diagnose
silently.
A negative embedding is optional; the templates accept one via the
negative_embedding argument (e.g. DeepNegative_xl_v1).
Install
pip install retiform-comfyui-mcpThe distribution is
retiform-comfyui-mcp; the installed module iscomfyui_mcp_serverand the console script iscomfyui-mcp-server. The three names differ deliberately: PyPI rejects the barecomfyui-mcp-serveras too similar to two existing projects, and keeping the module path and the script name stable means an install never breaks a working MCP client config.
Or from source:
git clone https://github.com/retiform-labs/comfyui-mcp-server
cd comfyui-mcp-server
pip install -e ".[dev]"
mcpis pinned below 2.0 -- in the MCP SDK 2.x line,mcp.server.fastmcpis a compatibility stub that raises on import. Do not widen that pin without migrating the server toMCPServer.
Configure
All configuration is environment-driven. Nothing is assumed about where ComfyUI lives.
Variable | Default | Meaning |
|
| ComfyUI host |
|
| ComfyUI port |
|
| ComfyUI install root (the dir with |
|
| Models root |
|
| Where renders land |
|
| CLIP vision tower for reference-guided generation |
|
| IP-Adapter weight (plus variant) |
|
| IP-Adapter weight used by the VRAM-saving fallback |
| (none) | Bearer token for gated model hosts, so it need not travel through a tool argument |
MCP client
{
"mcpServers": {
"comfyui": {
"command": "comfyui-mcp-server",
"env": { "COMFYUI_PATH": "/opt/ComfyUI" }
}
}
}VRAM behaviour
The MCP server is a separate process from ComfyUI. It never allocates CUDA
tensors, so torch.cuda.memory_allocated() inside it is structurally zero no
matter what ComfyUI is holding. This server therefore reads VRAM from the
driver (nvidia-smi) and releases it by asking ComfyUI to unload --
get_vram_usage-- live used/free/total from the driveremergency_cleanup--POST /free {"unload_models": true, "free_memory": true}on ComfyUI, reporting real before/after MB andfreed_mb
torch is deliberately not a dependency. It cost ~2GB of CUDA to produce a
number that measured the wrong process.
Unloading after every job is usually the wrong trade: the next job then pays a full model-load penalty. If you release between jobs, release at batch boundaries.
Provenance
Generated PNGs carry an A1111-compatible parameters block plus a structured
GenerationInfo record. Values that were not supplied are written as ? and are
never defaulted -- an invented parameter in an embedded block is a permanent,
machine-readable lie.
Images rendered before the rename carry the same payload under the key
LogoGenInfo. Both keys are read; only the current one is written.
Development
pip install -e ".[dev]"
python -m unittest discover -s tests -v
ruff check src testsNothing under src/ may contain an absolute filesystem path; a test enforces
this, because a package that only works on its author's machine is broken for
everyone else.
License
MIT -- see LICENSE.
Copyright (c) 2026 David Newman and Guan.
Sponsors
If comfyui-mcp-server is useful to you, consider supporting its continued development:
Bitcoin:
bc1q0gd3mwjg3zy9sghv22kmpg823vss4c0zzdzg24Solana:
Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6Ethereum / EVM:
0x2733ff7c865C56d565a99BE1DC11B81cc76850A5XRP Ledger:
r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG
Crafted with ❤️ by Retiform Labs
Available Tools
13 toolsbatch_generateB
Submit batch jobs with optional per-generation randomization.
Args: prompts: List of positive prompt strings (one per job) shared_params: Static parameters applied to all generations randomize: Per-generation randomization specs (override shared_params) Supports: scalar, [min, max] range, choice pool, "random"/"random_unsafe" deduplicate_seeds: Ensure unique seeds across all jobs in this batch priority: Queue priority hint ("high" | "normal")
Returns: Batch metadata with batch_id, total_jobs, queued_jobs, job_ids
Inputs: prompts (required), priority, randomize, keep_loaded, +2 more. Returns: object
batch_generate_ipadapterB
Submit batch IP-Adapter jobs with optional per-generation randomization.
All jobs in the batch use the SAME reference images, but each prompt creates a distinct output. Supports parameter randomization per job.
Args: prompts: List of positive prompt strings (one per job) reference_images: Shared reference images for all jobs in batch shared_params: Static parameters applied to all generations randomize: Per-generation randomization specs (overrides shared_params) deduplicate_seeds: Ensure unique seeds across batch priority: Queue priority hint
Returns: Batch metadata with batch_id, total_jobs, queued_jobs, job_ids
Inputs: prompts (required), reference_images (required), priority, randomize, +3 more. Returns: object
download_modelA
Download a model file into the right ComfyUI models subdirectory.
The contract is deliberately tight, because this writes into the user's model tree:
filenamemust be a bare name -- no path separators, no...The extension must be plausible for the model type, so a stray
.shcannot be dropped intomodels/.Only
http/httpsURLs are fetched, and redirects are not followed to non-HTTP schemes.The write is atomic: a partial download lands on a
.partfile and is renamed only on success, so an interrupted transfer can never leave a corrupt.safetensorsthat ComfyUI will later try to load.
api_token is sent as a bearer header for gated hosts and is never
logged. It may also be supplied via COMFYUI_DOWNLOAD_TOKEN so it does
not have to travel through a tool argument.
Inputs: url (required), filename (required), model_type (required), api_token. Returns: object
emergency_cleanupB
Recover GPU memory by unloading ComfyUI's models.
ComfyUI is a separate process and holds the models, so torch.cuda in THIS process can never free them. POST /free on ComfyUI is the only real lever; nvidia-smi measures the result.
Inputs: restart_comfyui. Returns: object
generate_imageA
Submit an async text-to-image generation job.
Runs the packaged SDXL workflow: loads the diffusion model, encodes the
prompt pair, samples, and decodes. Returns immediately with a job id --
poll get_job_status for the result.
Args:
prompt: What to generate.
negative_embedding: Textual-inversion embedding appended to the negative prompt.
negative_prompt: What to avoid.
width: Output width in pixels.
height: Output height in pixels.
steps: Sampling steps. More is slower and usually better.
cfg_scale: Classifier-free guidance. Higher follows the prompt harder.
sampler: Sampler name, as ComfyUI exposes it.
scheduler: Scheduler name, as ComfyUI exposes it.
lora: Single LoRA filename from comfyui/models/loras/.
lora_weight: Weight for lora.
loras: Several LoRAs at once, as [{"name": ..., "weight": ...}].
seed: Fixed seed for reproducibility. Omitted means a random one.
output_format: png keeps provenance metadata; other values do not.
Returns:
A job record with job_id, the resolved parameters, and the workflow path.
Inputs: prompt (required), lora, seed, loras, +10 more. Returns: object
generate_ipadapterB
Generate image with IP-Adapter multi-reference style blending.
Feeds 1--4 reference images into the diffusion model to influence style, composition, and content of the generated output.
Args: prompt: Text prompt describing desired output reference_images: List of 1-4 image filenames from comfyui/input/ negative_prompt: What to avoid in the output negative_embedding: Textual inversion embedding name (e.g., "DeepNegative_xl_v1") to append to negative prompt width: Output width (512 recommended for 6GB VRAM) height: Output height steps: Sampling steps (10-20 for speed, 30+ for quality) cfg_scale: Classifier-free guidance scale sampler: Sampling algorithm scheduler: Noise schedule seed: Fixed seed for reproducibility (None = random) reference_weight: How strongly reference images influence output (0.0-1.0+) weight_type: "style transfer", "composition", "linear", etc. denoise: Denoising strength (1.0 = full generation) start_at: When to start applying IP-Adapter (0.0 = beginning) end_at: When to stop applying IP-Adapter (1.0 = end) embeds_scaling: Embedding scaling strategy loras: Optional list of LoRA configs [{"name": str, "weight": float}] output_format: Always "png" for now output_prefix: Filename prefix for saved images
Returns: Dict with job_id, status, queue_position
Inputs: prompt (required), reference_images (required), seed, loras, +18 more. Returns: object
get_comfyui_statusA
Check if ComfyUI is running
Inputs: no named parameters. Returns: object
get_job_statusC
Poll for job completion
Inputs: job_id (required). Returns: object
get_vram_usageA
Monitor live GPU memory and utilisation.
Reads the driver, not torch: this process holds no CUDA tensors, so torch would report 0 no matter what ComfyUI is actually holding.
Inputs: no named parameters. Returns: object
list_modelsB
Discover available models: unet, clip, vae, lora
Inputs: model_type. Returns: result
start_comfyuiC
Launch ComfyUI with VRAM-optimized flags
Inputs: fp16, port, lowvram. Returns: object
stop_comfyuiC
Graceful shutdown of ComfyUI server
Inputs: force. Returns: object
system_checkA
Verify system readiness: GPU, driver, VRAM.
Reads the driver, not torch. This process never allocates CUDA tensors, so torch.cuda would report 0 whether or not ComfyUI is holding every byte.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
The core generation matrix is reasonably separable (generate_image vs generate_ipadapter vs batch_generate vs batch_generate_ipadapter), but system_check and get_vram_usage both read driver-level GPU/VRAM data and are easy to swap, and get_comfyui_status vs get_job_status are only distinguished by careful reading. Four near-parallel generation tools plus two overlapping health tools make misselection plausible without studying descriptions.
All names are snake_case and mostly verb-first (get_vram_usage, get_job_status, start_comfyui, list_models). Minor deviations: system_check is noun-first, the comfyui_ prefix is applied inconsistently (start_comfyui/stop_comfyui but not generate_image), and batch variants use a prefix while single variants use a suffix.
Thirteen tools is well within a healthy range and each maps to a distinct operational need: lifecycle control, monitoring, model management, and four generation paths. Nothing feels padded or missing at the count level.
Lifecycle (start/stop/status), GPU monitoring/cleanup, model discovery and download, async generation with polling, plus batch and IP-Adapter variants give broad coverage. Gaps remain: no cancel/abort job, no queue management or job listing, and no way to run custom or list stored workflows.
Maintenance
Related MCP Connectors
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Build and run visual creative-production workflows from your AI agent.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables comprehensive ComfyUI workflow automation including image generation, workflow management, node discovery, and system monitoring through natural language interactions with local or remote ComfyUI servers.3163 PyPI14MIT
- AlicenseNot gradedqualityDmaintenanceGive AI agents full control over your local ComfyUI by exposing 77 tools for workflow management, image generation, model handling, and real-time canvas control.4AGPL 3.0
- AlicenseAqualityBmaintenanceEnables AI assistants to remotely control a ComfyUI installation via its HTTP API, including generating and editing images, creating transparent assets, generating video and audio, tracking the queue, and downloading results.20MIT
- FlicenseAqualityBmaintenanceExposes the workflows saved in a ComfyUI server (local, remote, or vast.ai) as MCP tools, letting agents list them, inspect their inputs, and run them with their own prompts, images, seeds, and per-run node toggles. It also reports server/GPU status, tracks and downloads job outputs, and uploads images or browses model folders.10-