comfyui-mcp-secure
A secure MCP server for ComfyUI that enables AI assistants to generate images, run/manage workflows, discover resources, and manage custom nodes — with layered security controls.
Generate images via text-to-image, image-to-image, inpainting, and upscaling.
Run arbitrary ComfyUI workflows synchronously, in streaming mode, or as background tasks with real-time progress.
Create, modify, summarize, analyze, and validate workflows from built-in templates.
Manage jobs: list, inspect, cancel, interrupt, clear queue, and track execution progress.
Discover models, node types, extensions, workflows, system info, and server features.
Search, install, uninstall, and update custom node packs via ComfyUI-Manager.
Search HuggingFace/CivitAI for models, download them via Model Manager, and check/cancel downloads.
Upload images/masks, retrieve generated images, list outputs, and extract workflow metadata from PNGs.
Browse read-only state via resources (models, nodes, queue, system, settings) and reusable prompt recipes.
Security layers: workflow inspector flags dangerous nodes/inputs, path sanitizer blocks traversal, rate limiting, audit logging with redaction, and selective API surface.
Configurable audit vs enforce mode with user elicitation on security warnings.
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-secure generate an image of a cat in a hat"
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-secure
A secure MCP (Model Context Protocol) server for ComfyUI. Enables AI assistants to generate images, run workflows, and manage jobs through ComfyUI — with built-in security controls that existing ComfyUI MCP servers lack.
Using OpenCode? This repo ships agent configuration under
.opencode/— grounding rules (.opencode/rules/), a read-onlyreviewsubagent, a/preflightcommand, and a graphify plugin — all pre-wired to the MCP server. See AGENTS.md for the entry point. The server itself works with any MCP client over stdio or Streamable HTTP.
Why this exists
Every existing ComfyUI MCP server is a thin passthrough to ComfyUI's API with no security guardrails. They allow arbitrary workflow execution (including malicious custom nodes that run eval/exec), have no input validation, no file path sanitization, no rate limiting, and no audit trail.
This server adds five security layers between the AI assistant and ComfyUI:
Layer | What it does |
Workflow Inspector | Parses every workflow before execution, extracts node types, flags dangerous patterns ( |
Path Sanitizer | Validates all filenames, subfolders, and URL path segments — blocks path traversal ( |
SecurityMiddleware | Centralized rate-limit checks + entry audit logging across every tool call via the FastMCP 4 |
Audit Logger | Structured JSON logging of every operation with automatic redaction of sensitive fields (tokens, passwords). |
Selective API Surface | Only exposes safe ComfyUI endpoints. Dangerous endpoints ( |
Resources & Prompts (FastMCP 4)
The server exposes read-only ComfyUI state as resources the LLM can browse by URI without a tool call, and prompts as reusable workflow-template recipes:
Resources:
comfyui://models/{folder},comfyui://nodes/installed,comfyui://queue,comfyui://system,comfyui://settingsPrompts:
txt2img_prompt,img2img_prompt,inpaint_prompt,upscale_prompt
Dependency injection & background tasks (FastMCP 4)
Depends() DI — tool modules may declare their dependencies (
client,audit,inspector,limiter) viaDepends()providers (auto-excluded from the MCP schema) instead of receiving them throughregister_*_tools()factories.history_di.pyis the canonical DI module; the remaining tools migrate incrementally.Background tasks (optional) — long-running workflows can run as background tasks via
TasksExtension(Docket-backed) instead of holding the request open. Disabled by default; see Background tasks.
Real-time progress tracking
When wait=True is passed to comfyui_generate_image or comfyui_run_workflow, the server connects to ComfyUI's WebSocket to track execution in real time — reporting step progress, current node, and output files when complete. If the WebSocket connection fails, it automatically falls back to HTTP polling. Use comfyui_get_progress to check status of any job at any time.
For workflow streaming, use the mode that matches your use case:
comfyui_run_workflow(..., wait=True)returns a summarized, tool-friendly completion response.comfyui_run_workflow_stream(...)returns raw WebSocket event flow (progress,executing,executed, etc.) plus final status and outputs.
Structured output & rich schemas
Tools expose Pydantic Field constraints on input parameters (ranges, lengths, descriptions) and outputSchema for structured responses. MCP clients get:
Input validation: Parameter constraints like
steps: 1-100,cfg: 1.0-30.0,width: 64-4096appear in the tool's JSON schemaOutput schemas: 26 tools return structured data with auto-generated
outputSchema, enabling clients to parse responses without guessing the shapeStreamable HTTP transport: Optional remote transport via
transport.remote.enabledusing the MCP spec's recommended Streamable HTTP protocol
Related MCP server: ComfyUI MCP
Recent Breaking Changes (2026-05)
2.1.0 (2026-05-12) is additive — no breaking changes since 2.0.0. Adds
comfyui_analyze_workflow, replaces the bespoke Ollama eval runner with an Inspect AI Task module, and introduces a Phase 5 live-execution eval. See the CHANGELOG for the full per-PR breakdown. The breaking changes below all shipped in 2.0.0.
Parameter renames — update keyword arguments (positional calls are unaffected):
comfyui_install_custom_node,comfyui_uninstall_custom_node,comfyui_update_custom_node:id→node_id.comfyui_summarize_workflow:format→output_format, restricted totextormermaidvia a PydanticLiteral.
Response-shape changes — these tools now return the standard pagination envelope {items, total, offset, limit, has_more} instead of bare lists or raw dicts:
comfyui_list_extensions(was:list[str])comfyui_list_model_folders(was:list[str])comfyui_list_workflows(was:dict[package_name, list[template]]; now flattened toitems: [{package, templates}])
Callers must update to read result["items"] instead of indexing the response directly. The new envelope also exposes limit and offset parameters for pagination.
Unified return envelope for workflow-submitting tools — comfyui_run_workflow, comfyui_run_workflow_stream, comfyui_generate_image, comfyui_transform_image, comfyui_inpaint_image, comfyui_upscale_image now all return a uniform dict[str, Any] regardless of wait/stream mode:
{
"status": "submitted" | "completed" | "interrupted" | "error" | "timeout",
"prompt_id": "<uuid>",
"warnings": [...] # only when the workflow inspector produced warnings
# When wait=True or stream:
"outputs": [...],
"elapsed_seconds": float,
"step" / "total_steps" / "current_node" / "queue_position": ...,
# When stream:
"events": [...]
}Previously these tools returned either a free-form sentence (wait=False) or a JSON-serialized string (wait=True/stream), forcing callers to try both shapes. Callers that previously parsed the response as text — or via json.loads() for wait=True — must update to read fields directly off the dict.
Quick start
Prerequisites
Python 3.12+
uv package manager
A running ComfyUI instance (local or remote)
Install
Option A: From PyPI
pip install comfyui-mcp-secureFor an isolated CLI install, use one of:
uv tool install comfyui-mcp-secure
pipx install comfyui-mcp-secureFor a one-shot run without installing first:
uvx comfyui-mcp-secure --helpOption B: From source (recommended for development)
git clone https://github.com/hybridindie/comfyui_mcp.git
cd comfyui_mcp
uv syncOption C: Docker (no clone required)
docker pull ghcr.io/hybridindie/comfyui_mcp:latestOr build locally from the repo:
docker build -t comfyui-mcp-secure .Configure
Create a minimal config for your ComfyUI instance:
mkdir -p ~/.comfyui-mcp
cat > ~/.comfyui-mcp/config.yaml << 'EOF'
comfyui:
url: "http://127.0.0.1:8188"
EOFFor a remote server:
cat > ~/.comfyui-mcp/config.yaml << 'EOF'
comfyui:
url: "https://your-gpu-server:8188"
EOFAdd to your MCP client
The MCP server communicates over stdio. Add one of the following configurations to your MCP client (OpenCode, Claude Desktop, Cursor, or any stdio MCP client) depending on how you installed.
From source (uv):
{
"mcpServers": {
"comfyui": {
"command": "uv",
"args": ["--directory", "/path/to/comfyui_mcp", "run", "comfyui-mcp-secure"]
}
}
}From PyPI / pipx / uv tool install:
{
"mcpServers": {
"comfyui": {
"command": "comfyui-mcp-secure"
}
}
}From PyPI without a persistent install (uvx):
{
"mcpServers": {
"comfyui": {
"command": "uvx",
"args": ["comfyui-mcp-secure"]
}
}
}Docker (GitHub Container Registry):
{
"mcpServers": {
"comfyui": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "COMFYUI_URL=http://host.docker.internal:8188",
"-v", "~/.comfyui-mcp:/home/app/.comfyui-mcp:ro",
"ghcr.io/hybridindie/comfyui_mcp:latest"
]
}
}
}Note:
host.docker.internalroutes to your host machine from inside Docker. If ComfyUI runs on a remote server, replace with that server's URL. On Linux, you may need to add--add-host=host.docker.internal:host-gateway.
Agent configuration (OpenCode)
This repository ships agent configuration under .opencode/ for OpenCode (and any harness that reads AGENTS.md). The server itself is harness-agnostic — it works with any MCP client over stdio or Streamable HTTP.
Agent-related files in this repo:
AGENTS.md— harness-agnostic entry point; index of the grounding rules.opencode/opencode.json— wirescontext7(MCP/FastMCP/Pydantic/httpx docs), areviewsubagent, a/preflightcommand, the graphify plugin, and awatcher.ignore.opencode/rules/— path-scoped constitutional rules (security, architecture, tools, testing, workflow, enforcement, graphify); loaded asinstructionsinopencode.json.opencode/agents/review.md— read-only pre-PR reviewer subagent.opencode/commands/preflight.md—/preflightcommand (lint/format/type/tests gate).opencode/hooks/check-no-skipped-tests.sh— zero-skip suite-health gate.opencode/plugins/graphify.js— knowledge-graph reminder pluginskills/— convenience recipes that wrap common multi-tool flows (gen,workflow,status,progress,history,models,troubleshooting,workflows)
Skills
The skills/ directory contains pre-authored recipes that wrap common multi-tool flows so a user doesn't have to choreograph the calls themselves. They are harness-agnostic markdown and work with any agent that loads them. The two "knowledge" skills (workflows, troubleshooting) are auto-applied when the conversation matches their topic.
Skill | What it does |
| Generate an image. Picks a model via |
| Build a workflow from a built-in template, validate it, then offer to run or modify. |
| Knowledge skill — auto-applied when the conversation involves building/modifying workflows. Covers workflow JSON format, common node chains (txt2img/img2img/ControlNet/LoRA), and the key node reference. |
| Show queue state (running + pending jobs). |
| Per-job execution progress (current node, step X of Y, status). |
| Recent completions with prompt IDs and output filenames. |
| List models in a folder type (defaults to |
| Knowledge skill — auto-applied when users report connection, model, workflow, or security errors. Covers connection failures, model-not-found, workflow execution failures, queue-stuck, security warnings, and the two upstream-plugin (ComfyUI-Manager, ComfyUI-Model-Manager) setup issues. |
Security warnings in the tool response
The workflow inspector and node auditor surface warnings directly in the tool response envelope. When comfyui_run_workflow, comfyui_generate_image, comfyui_audit_dangerous_nodes, comfyui_install_custom_node, or comfyui_update_custom_node detect dangerous node patterns ("Dangerous node type", "Suspicious input", or dangerous.count > 0), the response includes a warnings array. The agent reads this from the tool output and asks the user to confirm before proceeding — exactly the audit-mode-default behavior the project ships with.
End-to-end example
A user asks to generate "a yellow apple, photorealistic, 4k". The layers cooperate:
The
genskill parses the prompt and applies defaults (512×512, 20 steps, cfg 7.0).It calls
comfyui_list_models(folder="checkpoints"), picks an available model from the paginateditemslist, and confirms with the user if ambiguous.It calls
comfyui_generate_image(prompt=..., model=..., wait=True).Server-side, the MCP tool runs
WorkflowInspector.inspect()on the workflow before submitting it to ComfyUI. With a clean built-in workflow there are no warnings.ComfyUI executes; the tool blocks until the unified envelope comes back with
status="completed".The skill reads
result["outputs"][0](a{node_id, filename, subfolder}dict), callscomfyui_get_image(filename=..., subfolder="output", preview_format="webp", preview_quality=80)for a cheap thumbnail, and presents the image inline.
Contrast that with running a user-supplied custom workflow that contains an Exec-class node: step 4's inspector emits warnings: ["Dangerous node type: Exec..."], and the response envelope carries:
SECURITY: Dangerous node patterns detected. Review the audit results above before proceeding.The agent sees this in the tool output and asks the user to confirm before continuing — exactly the audit-mode-default behavior the project ships with.
Verify
# From source
uv run python -c "from comfyui_mcp.server import mcp; print(f'Server {mcp.name!r} ready')"
# Docker
docker run --rm ghcr.io/hybridindie/comfyui_mcp:latest --helpTools
Generation & Workflows
Tool | Description |
| Text-to-image using a built-in workflow. Params: prompt, negative_prompt, width, height, steps, cfg, model. Set |
| Image-to-image transformation. Params: image (filename), prompt, negative_prompt, strength (0.0-1.0), steps, cfg, model. Input must be uploaded via |
| Inpaint masked regions of an image. Params: image, mask (filenames), prompt, negative_prompt, strength, steps, cfg, model. Both files must be uploaded first. |
| Upscale an image using a model-based upscaler. Params: image (filename), upscale_model (default: RealESRGAN_x4plus.pth). |
| Submit arbitrary ComfyUI workflow JSON. Inspected for dangerous nodes before execution. Set |
| Submit workflow JSON and capture ComfyUI websocket stream events ( |
| Summarize a workflow's structure, data flow, models, and parameters. Supports |
| Create a workflow from templates including txt2img/img2img/upscale/inpaint, txt2vid_animatediff/txt2vid_wan, controlnet_canny/controlnet_depth/controlnet_openpose, ip_adapter, lora_stack, face_restore, flux_txt2img, and sdxl_txt2img. |
| Apply batch operations (add_node, remove_node, set_input, connect, disconnect) to a workflow. |
| Return a structured analysis of a workflow as a dict ( |
| Validate workflow structure, server compatibility, security, and loop integrity (paired Start/End Loops, no escapes, no accumulate-from-body errors — mirrors upstream Core Loops validation). |
Job Management
Tool | Description |
| Get current execution queue state. |
| List jobs across queue + history with status filter, sorting, and pagination. |
| Look up a single job (queued/running/finished) by prompt_id. |
| Cancel a running or queued job. Uses the native |
| Batch-cancel one or more jobs by prompt_id via |
| Interrupt the running workflow (global, or targeted via optional prompt_id). |
| Get detailed queue status including running and pending prompts. |
| Clear pending and/or running items from the queue. |
| Get execution progress for a workflow by prompt_id. Returns status, queue position, and outputs. |
Discovery
Tool | Description |
| List available models by folder (checkpoints, loras, vae, etc.). |
| List models in a folder with file metadata (name, |
| Fetch a model's preview image via |
| List all available node types. |
| Get detailed info about a specific node type. |
| List saved workflow templates. |
| List available ComfyUI extensions. |
| Get ComfyUI server features and capabilities ( |
| List available model folder types. |
| Get metadata for a specific model file. |
| Scan all installed nodes to identify potentially dangerous ones. |
| List available reusable subgraph templates from ComfyUI ( |
| Fetch a single subgraph's JSON for inspection or insertion ( |
| Sanitized GPU VRAM, queue depth, and ComfyUI version (whitelist-filtered from |
| Read ComfyUI server settings (sampler defaults, UI prefs, feature flags) from |
| Merge new settings into the ComfyUI server config via |
Custom Node Management
Tool | Description |
| Search ComfyUI Manager registry custom node packs by name/description/author. |
| Queue install for a custom node pack by |
| Queue uninstall for a custom node pack by |
| Queue update for a custom node pack by |
| Get custom node queue status (pending/running/completed). |
Requires: ComfyUI-Manager available on the target ComfyUI server. If unavailable, node-management tools return a helpful error.
History
Tool | Description |
| Browse execution history (read-only). Server-side paging via |
Model Search & Download
Tool | Description |
| Search HuggingFace or CivitAI for models. Returns name, download URL, size, and stats. |
| Download a model via ComfyUI-Model-Manager. URL and extension validated. |
| Check status of active model downloads (progress, speed, status). |
| Cancel or clean up a model download task. |
| Return recommended sampler/scheduler/steps/CFG defaults for a model family. |
| Return model-family prompt engineering tips and negative prompt guidance. |
Requires: ComfyUI-Model-Manager installed in your ComfyUI instance. Download tools are gated behind lazy detection — if Model Manager is not installed, these tools return a helpful error message.
comfyui_search_modelsworks without it.
Server capability flags (comfyui_get_server_features)
ComfyUI (v0.38+) advertises its capabilities at GET /features. Meaningful keys:
Key | Meaning |
| Server-rendered preview thumbnails (webp/jpeg) available via |
| Model listings carry type tags |
| Maximum upload payload in bytes (enforced locally by |
| Server exposes a node replacement map ( |
| The SQLite asset catalogue is enabled ( |
| ComfyUI-Manager exposes its v4 API |
Older servers may omit keys — always treat them as optional. ComfyUI run-mode flags worth knowing (upstream, v0.38+): --offline (no outbound calls at all), --disable-partner-nodes (deprecates --disable-api-nodes; gates third-party API nodes like BFL/Ideogram/HeyGen).
Model Manager download lifecycle
Model Manager tracks downloads as tasks. After a download completes, the task remains in the list with status: "pause" and progress: 100 — this is upstream Model Manager behavior. Call comfyui_cancel_download to remove it:
comfyui_download_model(url="...", folder="checkpoints", filename="model.safetensors")
→ { "taskId": "abc123", ... }
comfyui_get_download_tasks()
→ { "tasks": [{ "taskId": "abc123", "status": "pause", "progress": 100, ... }] }
comfyui_cancel_download(task_id="abc123")
→ { "success": true, ... }The comfyui_download_model tool always sends a previewFile field (required by Model Manager even when empty). Omitting it causes the server to silently fail and delete the task.
File Operations
Tool | Description |
| Upload a base64-encoded image to ComfyUI. Path-sanitized. Params: filename, image_data, subfolder, |
| Download a generated image. |
| List generated output filenames from history. |
| Upload a mask image to ComfyUI. Path-sanitized. Params: filename, mask_data, original_image, subfolder, original_subfolder, |
| Extract embedded workflow and prompt metadata from a ComfyUI-generated PNG. |
Resources
Read-only state the LLM can browse by URI without a tool call. Templated resources inherit FastMCP 4's built-in path-traversal screening.
URI | Description |
| List models in a folder (checkpoints, loras, vae, etc.). Path-traversal in |
| Sorted list of all available ComfyUI node class types from |
| Current queue state — running and pending job counts. |
| Whitelisted system info: ComfyUI version, GPU VRAM, queue counts. Sensitive fields (hostname, OS, CPU, paths) excluded. |
| ComfyUI server settings (sampler defaults, UI prefs, feature flags) from |
Prompts
Reusable, parameterized prompt recipes for the built-in workflow templates. Return a plain string the LLM can use as guidance.
Prompt | Description |
| Text-to-image recipe. Params: |
| Image-to-image recipe. Params: |
| Inpaint recipe. Params: |
| Upscale recipe. Params: |
Deliberately not exposed
These ComfyUI endpoints are never proxied due to security risks:
/userdata— arbitrary file read/write/free— unload models (DoS vector)/users— user management/historyPOST — delete history
/system_stats is called internally only by comfyui_get_system_info, which applies a strict whitelist and never forwards the raw response.
Configuration
Config file: ~/.comfyui-mcp/config.yaml
comfyui:
url: "http://127.0.0.1:8188" # ComfyUI server URL
external_url: null # Optional public URL for get_image URL responses
# If unset, URL responses use comfyui.url
tls_verify: true # TLS certificate verification
timeout_connect: 30 # Connection timeout (seconds)
timeout_read: 300 # Read timeout (seconds)
security:
mode: "audit" # "audit" (log only) or "enforce" (block unapproved)
allowed_nodes: [] # Enforce mode: only these nodes can run
dangerous_nodes: # Always flagged in audit log (showing subset)
- "Terminal" # comfyui-colab: shell via subprocess
- "interpreter_tool" # comfyui_LLM_party: exec/eval
- "KY_Eval_Python" # ComfyUI-KYNode: exec Python
- "Image Send HTTP" # was-node-suite: arbitrary HTTP
- "Load Text File" # was-node-suite: reads arbitrary files
- "Save Text File" # was-node-suite: writes arbitrary files
# ... see config.py _DEFAULT_DANGEROUS_NODES for the full list
max_upload_size_mb: 50
allowed_extensions:
- ".png"
- ".jpg"
- ".jpeg"
- ".webp"
- ".gif"
- ".json"
rate_limits: # Requests per minute
workflow: 10
generation: 10
file_ops: 30
read_only: 60
model_search:
huggingface_token: "" # Optional; needed for gated/private HF models
civitai_api_key: "" # Optional; needed for auth-only CivitAI access
max_search_results: 10
logging:
audit_file: "~/.comfyui-mcp/audit.log"
transport:
remote:
enabled: false
host: "127.0.0.1"
port: 8080When transport.remote.enabled is true, the server starts in Streamable HTTP mode and binds to transport.remote.host and transport.remote.port.
Keep this bound to localhost unless you are running behind authenticated TLS reverse proxy infrastructure.
Environment variables
Environment variables override config file values:
Variable | Overrides |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HuggingFace and CivitAI API keys
comfyui_search_models and comfyui_download_model work without API keys for many public models. Add keys when you need access to gated/private resources or higher provider limits.
Set them in config:
model_search:
huggingface_token: "hf_xxx"
civitai_api_key: "xxx"Or via environment variables:
export COMFYUI_HUGGINGFACE_TOKEN="hf_xxx"
export COMFYUI_CIVITAI_API_KEY="xxx"Security notes:
Prefer environment variables in production so secrets do not live in files committed to git.
Audit logs redact sensitive fields (
token,api_key, etc.), but avoid printing secrets in shell history when possible.
Security modes
Audit mode (default)
Every workflow is inspected and logged, but nothing is blocked. Use this during development to understand what nodes your workflows use.
security:
mode: "audit"Audit log entries look like:
{
"timestamp": "2026-02-25T14:30:00+00:00",
"tool": "run_workflow",
"action": "inspected",
"nodes_used": ["KSampler", "CLIPTextEncode", "VAEDecode", "SaveImage"],
"warnings": []
}When a dangerous node is detected, warnings are included in the tool response:
Workflow submitted. prompt_id: abc123
⚠️ Warnings detected:
- Dangerous node type: ExecutePython
- Suspicious input in node 5 (ExecutePython), field 'code'The MCP instructions tell the LLM to inform users and ask for confirmation before proceeding when warnings are present.
Building your dangerous node list
Use the comfyui_audit_dangerous_nodes tool to scan your ComfyUI installation for potentially dangerous nodes:
Tool | Description |
| Scans all installed nodes and returns dangerous/suspicious ones with reasons |
Run this once to see what dangerous nodes are installed:
comfyui_audit_dangerous_nodes() → {
"total_nodes": 456,
"dangerous": {
"count": 12,
"nodes": [
{"class": "ExecutePython", "reason": "Name matches pattern: \\bexec\\b"},
{"class": "RunPython", "reason": "Name matches pattern: \\brunpython\\b"},
{"class": "ShellCommand", "reason": "Name matches pattern: \\bshell\\b"}
]
},
"suspicious": {...}
}Add these to your config:
security:
mode: "audit"
dangerous_nodes:
- "ExecutePython" # from audit_dangerous_nodes
- "RunPython"
- "ShellCommand"
# ... other nodes found by auditEnforce mode
Only explicitly approved nodes can run. Any workflow containing an unapproved node is rejected.
security:
mode: "enforce"
allowed_nodes:
- "KSampler"
- "CheckpointLoaderSimple"
- "CLIPTextEncode"
- "VAEDecode"
- "EmptyLatentImage"
- "SaveImage"
- "LoadImage"
- "LoraLoader"Tip: Use comfyui_audit_dangerous_nodes to identify dangerous nodes, run workflows in audit mode to see which nodes you use, then switch to enforce mode with that allowlist.
Elicitation gate (Phase 5): when enforce mode is on and the inspector produces warnings (dangerous-node types, suspicious inputs like eval()/exec(), or missing models), the generation tools (comfyui_run_workflow, comfyui_generate_image, comfyui_transform_image, comfyui_inpaint_image, comfyui_upscale_image) ask the user to confirm before submitting — ctx.elicit(..., response_type=bool). A decline or cancel raises WorkflowBlockedError without calling post_prompt. Unapproved-node enforcement (the allowed_nodes allowlist) still blocks hard inside the inspector before elicitation; the gate fires on the warning path. Programmatic callers without a live MCP context keep the pre-existing behavior (immediate WorkflowBlockedError in enforce mode with warnings).
Audit log
All tool invocations are logged as JSON lines to ~/.comfyui-mcp/audit.log:
# Watch the audit log in real time
tail -f ~/.comfyui-mcp/audit.log | python -m json.tool
# Find all workflows that used dangerous nodes
grep '"warnings":\[' ~/.comfyui-mcp/audit.log | grep -v '"warnings":\[\]'Sensitive fields (token, password, secret, api_key, authorization) are automatically redacted from log entries.
Security
Threat model
Threat | Impact | Mitigation |
Arbitrary code execution via workflow nodes | Critical | Workflow inspector (audit/enforce mode) |
Path traversal via file operations | High | Path sanitizer blocks |
Denial of service via request flooding | Medium | Token-bucket rate limiter per tool category |
Credential leakage in logs | Medium | Automatic redaction of |
Information disclosure via API | Low | Dangerous endpoints ( |
MITM on ComfyUI connection | Medium | Configurable TLS verification |
Security controls by component
Workflow Inspector (security/inspector.py)
Parses workflow JSON, extracts node types, checks against configurable blocklist
Recursive pattern matching for
__import__(),eval(),exec(),os.system(),subprocessin all input values (including nested dicts/lists)Audit mode: logs warnings, allows execution. Enforce mode: blocks unapproved nodes
Limitation: static blocklist can be bypassed with obfuscation or unknown custom nodes
Path Sanitizer (security/sanitizer.py)
Validates filenames, subfolders, and URL path segments: blocks path traversal, null bytes, absolute paths, control characters
URL path segment validation on discovery tools (
comfyui_list_models,comfyui_get_model_metadata) prevents folder/filename injectionAllowlist-based extension filtering (default:
.png,.jpg,.jpeg,.webp,.gif,.json)Handles percent-encoded inputs (URL decoding before validation)
Enforces max upload size (default 50MB), max filename length (255 chars)
Rate Limiter (security/rate_limit.py) + SecurityMiddleware (middleware.py)
Token-bucket per tool category: workflow (10/min), generation (10/min), file_ops (30/min), read_only (60/min)
In-memory only (resets on restart, no distributed support)
SecurityMiddlewarecentralizes rate-limit checks + entry audit logging across every tool call (FastMCP 4on_call_toolhook), so the per-toollimiter.check()/audit.async_log(action="called")boilerplate can be dropped. Tools keep their domain-specific lifecycle audit logs (submitted,completed, etc.)Sensitive tool arguments (
token,password,api_key, ...) are redacted by the middleware before the entry audit record is writtenmask_error_details=Trueon the server constructor masks internal exception tracebacks from clients — onlyToolErrormessages (which we control) include detailsBuilt-in FastMCP 4 middleware wired alongside
SecurityMiddleware(seebuild_middleware_stack()):ResponseCachingMiddleware(caches read-only tools + the 4comfyui://resources, 30s TTL),ResponseLimitingMiddleware(capslist_nodes/list_models/get_historypayloads at 500KB),PingMiddleware(keeps long-lived HTTP connections alive),StructuredLoggingMiddleware(ops/observability,include_payloads=False— the AuditLogger already redacts).
HTTP Client (client.py)
Configurable TLS verification, connect/read timeouts
Retries on connection errors with backoff (3 retries default). HTTP 4xx/5xx errors raised immediately (no retry)
WebSocket Progress (progress.py)
On-demand WebSocket connections for real-time execution tracking (step progress, current node, outputs)
Automatic HTTP polling fallback if WebSocket connection fails
TLS/SSL passthrough for secure ComfyUI connections
Per-prompt event filtering (ignores events from other concurrent jobs)
Configuration (config.py)
yaml.safe_loadonly, env var overrides limited to specific keys, Pydantic type validation
Production deployment
For production, run behind a reverse proxy (nginx, Traefik) to add TLS termination, authentication, and CSP headers. No PII is collected. No external telemetry.
Background tasks (optional, Phase 6)
Long-running workflows (comfyui_run_workflow(wait=True), image generation) can run as background tasks instead of holding the MCP request open. Disabled by default — most useful for the HTTP/remote transport where a long generation can return a task handle immediately and the client polls for progress.
tasks:
enabled: true
backend_url: "memory://" # in-memory (default, single-process)
# backend_url: "redis://localhost:6379/0" # persistent, horizontally scalableEnv overrides: COMFYUI_TASKS_ENABLED, COMFYUI_TASKS_BACKEND_URL. When enabled, the server registers TasksExtension (backed by Docket) and async tools become task-capable — a client that opts in to the tasks capability gets a handle and polls; a client that does not gets synchronous execution as before. Use the Redis backend for deployments where tasks must survive restarts or run across workers. ctx.elicit() is not supported inside a background task — use the guard pattern (InputRequiredResult) for mid-task user input when serving 2026-07-28 connections.
Architecture
flowchart TB
subgraph Client["LLM Client"]
MC[AI Assistant / MCP Client]
end
subgraph MCP["ComfyUI MCP Server (FastMCP 4)"]
CONFIG[Config<br/>YAML/env]
AL[Audit Logger<br/>JSON logs]
subgraph Security["Security Layers"]
WI[Workflow Inspector<br/>Dangerous nodes<br/>Suspicious input<br/>+ Elicitation gate]
PS[Path Sanitizer<br/>Traversal block<br/>Extension filter]
RL[Rate Limiter<br/>Token-bucket]
end
MW[SecurityMiddleware<br/>rate limit + entry audit<br/>on_call_tool hook]
DI[Dependencies<br/>Depends() providers]
subgraph Tools["Tool Groups"]
TG[generation.py<br/>jobs.py<br/>discovery.py<br/>history_di.py<br/>files.py]
end
RES[Resources<br/>comfyui://models, nodes, queue, system]
PR[Prompts<br/>txt2img, img2img, inpaint, upscale]
TASKS[TasksExtension<br/>optional, Docket-backed]
API[ComfyUI Client<br/>httpx]
WS[WebSocket Progress<br/>websockets]
end
subgraph ComfyUI["ComfyUI Server"]
CS[REST API<br/>port 8188]
CWS[WebSocket<br/>/ws]
end
MC <--MCP--> MCP
CONFIG --> MCP
AL --> MCP
MCP --> MW
MW --> Security
MW --> Tools
DI --> Tools
Security --> Tools
Tools --> API
Tools --> WS
API --httpx--> CS
WS --websockets--> CWSComponents
Component | File | Responsibility |
Server |
| Entry point, wires components, registers tools/resources/prompts/middleware |
Config |
| Pydantic settings, YAML loading, env overrides (incl. |
Client |
| Async HTTP client for ComfyUI REST API |
SecurityMiddleware |
| Centralized rate-limit + entry-audit via FastMCP 4 |
Dependencies |
|
|
Resources |
|
|
Prompts |
|
|
Progress |
| WebSocket progress tracking with HTTP polling fallback |
Audit |
| Structured JSON logging with redaction |
Workflow Inspector |
| Node type detection, dangerous pattern matching, elicitation gate |
Node Auditor |
| Scans installed nodes for dangerous patterns |
Path Sanitizer |
| Path traversal, extension filtering |
Rate Limiter |
| Token-bucket per tool category (enforced by |
Download Validator |
| URL domain/path and extension validation for downloads |
Model Checker |
| Proactive missing model detection in workflows |
Model Manager |
| Lazy detection of ComfyUI-Model-Manager availability |
Development
Project structure
src/comfyui_mcp/
├── server.py # MCP server entry point, wires all components + middleware
├── config.py # Pydantic settings, YAML loading, env overrides
├── client.py # Async HTTP client for ComfyUI API
├── middleware.py # SecurityMiddleware (rate limit + entry audit, on_call_tool)
├── dependencies.py # Depends() providers (client/audit/inspector/limiter singletons)
├── resources.py # @mcp.resource URIs (models, nodes, queue, system)
├── prompts.py # @mcp.prompt workflow-template recipes
├── progress.py # WebSocket progress tracking with HTTP polling fallback
├── pagination.py # Offset-based pagination helper for list tools
├── audit.py # Structured JSON audit logger
├── model_manager.py # Lazy Model Manager detection and validation
├── security/
│ ├── inspector.py # Workflow node inspection (audit/enforce)
│ ├── node_auditor.py # Scans installed nodes for dangerous patterns
│ ├── sanitizer.py # File path validation
│ ├── rate_limit.py # Token-bucket rate limiter
│ ├── download_validator.py # URL/extension validation for model downloads
│ └── model_checker.py # Proactive model availability checking
├── workflow/
│ ├── templates.py # Built-in workflow templates (txt2img, img2img, upscale, etc.)
│ ├── operations.py # Workflow graph operations (add/remove nodes, connect, etc.)
│ └── validation.py # Workflow analysis and validation
└── tools/
├── generation.py # generate_image, run_workflow, summarize_workflow (elicitation-gated)
├── workflow.py # create_workflow, modify_workflow, validate_workflow, analyze_workflow
├── jobs.py # get_queue, get_job, cancel_job, interrupt, get_progress
├── discovery.py # list_models, list_nodes, audit_dangerous_nodes, etc.
├── history_di.py # get_history (DI version — Depends())
├── files.py # upload_image, get_image, list_outputs, upload_mask, get_workflow_from_image
├── models.py # search_models, download_model, get_download_tasks, cancel_download
└── nodes.py # search/install/uninstall/update custom nodes
scripts/
├── smoke_test.py # Operator smoke-test against a live ComfyUI instance
├── compare_evals.py # Diff two Inspect AI eval runs (PASS/FAIL + per-tag breakdown)
└── run_multimodel_eval.py # Run one Task against N models in a single invocation
evals/
├── comfyui_mcp_task.py # Inspect AI Task definitions (Phase 4, Phase 5)
├── 2026-05-11-comfyui-mcp-v1.jsonl # Phase 4 dataset (10 static questions, tagged)
└── 2026-05-12-comfyui-mcp-phase5.jsonl # Phase 5 dataset (5 live-execution questions, tagged)Run tests
uv sync
uv run pytest -vEvaluation
The MCP ships with an Inspect AI-based eval harness for measuring how well an LLM uses the tools end-to-end. Two task suites are defined:
Phase 4 — 10 static questions exercising templates, presets, the prompting guide, and the workflow validator/summarizer. ~1-6 min per run for cloud-tier models.
Phase 5 — 5 live-execution questions exercising multi-step tool chains, state passing, recovery from intentionally broken workflows, and reading structured outputs. Generation questions actually submit work to the connected ComfyUI server (so you need one reachable at
$COMFYUI_URL).
Every question is tagged with what it tests (e.g. template, recovery,
state-passing, output-reading) so results can be sliced per category.
Run a single model against one suite:
COMFYUI_URL=https://comfyui.example.net uv run inspect eval \
evals/comfyui_mcp_task.py@comfyui_mcp_phase5 \
--model ollama/gpt-oss:120b-cloud \
--log-dir ./logs/phase5
uv run inspect view --log-dir ./logs/phase5Run one suite against N models in a single invocation (wraps the
eval_set() Python API because the CLI's --model flag is single-value
by Click's default):
uv run python scripts/run_multimodel_eval.py \
evals/comfyui_mcp_task.py@comfyui_mcp_phase4 \
--models ollama/gpt-oss:120b-cloud,ollama/qwen3-coder:480b-cloud,anthropic/claude-sonnet-4-6 \
--log-dir ./logs/phase4-cross-modelCompare two runs (per-sample PASS/FAIL diff plus a per-tag breakdown when either log has tagged samples):
uv run python scripts/compare_evals.py logs/phase4-before logs/phase4-afterEach path can be either a specific .eval file or a directory (uses the
most recent .eval by mtime).
Build and publish
Build the distributable artifacts locally:
uv build
uvx twine check dist/*Publish a release to PyPI:
# After bumping pyproject.toml [project].version and updating CHANGELOG.md
git tag v2.1.0
git push origin v2.1.0The GitHub Actions workflow in .github/workflows/pypi.yml builds the sdist and wheel, verifies the metadata, and publishes to PyPI using GitHub Trusted Publishing on tag push. The GitHub Release is created manually after the workflow succeeds (gh release create v<x.y.z>). Before the first release, create the comfyui-mcp-secure project on PyPI, configure a trusted publisher for this repository in the PyPI project settings, and use the pypi GitHub environment.
Smoke test against a live instance
Verify connectivity, Model Manager availability, and download lifecycle against a running ComfyUI server:
# Full test (connectivity + folder listing + download task lifecycle)
uv run python scripts/smoke_test.py
# Quick connectivity + folder check only
uv run python scripts/smoke_test.py --no-download
# Target a different server
uv run python scripts/smoke_test.py --url http://localhost:8188The download probe uses a tiny (~520 KB) safetensors file from hf-internal-testing/tiny-random-bert. The file is created with a timestamped name and cleaned up automatically on every run.
Docker
A pre-built Docker image is published to the GitHub Container Registry. No need to clone the repo.
docker pull ghcr.io/hybridindie/comfyui_mcp:latestHow it works
The container runs as a non-root app user with uv run comfyui-mcp-secure as its entrypoint, communicating over stdin/stdout (stdio). This makes it compatible with OpenCode, Claude Desktop, Cursor, and any MCP client. Config is read from /home/app/.comfyui-mcp/config.yaml inside the container — mount your local config directory to provide it, or use environment variables.
Running standalone
# Using the hosted image
docker run --rm -i \
-e COMFYUI_URL=http://host.docker.internal:8188 \
-v ~/.comfyui-mcp:/home/app/.comfyui-mcp:ro \
ghcr.io/hybridindie/comfyui_mcp:latest
# Or build and run locally
docker build -t comfyui-mcp-secure -f deploy/docker/Dockerfile .
docker run --rm -i \
-e COMFYUI_URL=http://host.docker.internal:8188 \
-v ~/.comfyui-mcp:/home/app/.comfyui-mcp:ro \
comfyui-mcp-secureLinux users: Add
--add-host=host.docker.internal:host-gatewayif usinghost.docker.internal.
Docker Compose
A docker-compose.yml is included in deploy/docker/ for persistent deployments:
# Start (from the repo root)
COMFYUI_URL=http://your-comfyui:8188 docker compose -f deploy/docker/docker-compose.yml up -d
# View logs
docker compose -f deploy/docker/docker-compose.yml logs -f comfyui-mcp-secureThe compose file mounts config.yaml (from the repo root) and persists audit logs to a named volume:
services:
comfyui-mcp-secure:
build:
context: ../..
dockerfile: deploy/docker/Dockerfile
image: comfyui-mcp-secure:latest
container_name: comfyui-mcp-secure
environment:
- COMFYUI_URL=${COMFYUI_URL:-http://comfyui:8188}
- COMFYUI_SECURITY_MODE=${COMFYUI_SECURITY_MODE:-audit}
volumes:
- ../../config.yaml:/home/app/.comfyui-mcp/config.yaml:ro
- comfyui-mcp-secure-data:/home/app/.comfyui-mcp/logs
restart: unless-stopped
volumes:
comfyui-mcp-secure-data:Connecting via Docker
See the Docker configuration in Quick Start above. The key points:
Use
docker run --rm -i(interactive, no detach) so stdio worksMount your config:
-v ~/.comfyui-mcp:/home/app/.comfyui-mcp:roSet
COMFYUI_URLto reach your ComfyUI instance from inside the containerUse
host.docker.internalto reach ComfyUI running on your host machineThe GHCR image (
ghcr.io/hybridindie/comfyui_mcp:latest) means no local build needed
License
MIT
Available Tools
46 toolscomfyui_analyze_workflowARead-onlyIdempotent
Analyze a ComfyUI workflow and return its structured shape.
Unlike ``comfyui_summarize_workflow`` (which formats a human-readable
text or Mermaid summary), this tool returns the raw analysis as a dict
so callers can read individual fields directly without parsing prose.
Args:
workflow (required): JSON string of the workflow to analyze. The
workflow JSON is a dict keyed by node ID; each value has
``class_type`` and ``inputs``.
Returns:
Dict with keys:
- ``node_count`` (int): number of nodes in the workflow.
- ``class_types`` (list[str]): every ``class_type`` in topological
order.
- ``flow`` (list[dict]): per-node info — ``node_id``, ``class_type``,
``display_name``, ``inputs`` — in topological order.
- ``models`` (list[dict]): single-field loader values, e.g.
``[{"name": "v1-5-pruned.safetensors", "type": "checkpoints"}]``.
- ``parameters`` (dict): flat key/value of common sampler/latent
parameters extracted from the graph (``steps``, ``cfg``, ``width``,
``height``, etc.).
- ``pipeline`` (str): coarse type — one of ``txt2img``,
``img2img``, ``upscale``, ``img2img -> upscale``,
``txt2img -> upscale``, or ``unknown``.
- ``prompt_nodes`` (list[str]): ids of ``CLIPTextEncode`` nodes
that are NOT wired into any sampler's ``negative`` input
(the analyzer treats every non-negative CLIPTextEncode as
a positive prompt — it does not separately verify that it
is wired into a sampler's positive input).
- ``negative_nodes`` (list[str]): ids of ``CLIPTextEncode`` nodes
wired into a sampler's ``negative`` input.
Display-name enrichment is best-effort via ComfyUI's ``/object_info``
endpoint; if the server is unreachable, ``display_name`` falls back to
the bare ``class_type``.
Inputs: workflow (required). Returns: object
comfyui_audit_dangerous_nodesARead-onlyIdempotent
Audit all installed nodes to identify potentially dangerous ones.
Scans for nodes that could execute arbitrary code, run shell commands,
or access the file system. Useful for building a dangerous node blacklist.
Returns:
Dictionary with dangerous and suspicious node counts and lists
Inputs: no named parameters. Returns: object
comfyui_cancel_downloadADestructive
Cancel and remove a model download task.
Args:
task_id: ID of the download task to cancel
Inputs: task_id (required). Returns: object
comfyui_cancel_jobADestructiveIdempotent
Cancel a running or queued job by its prompt_id.
Inputs: prompt_id (required). Returns: result
comfyui_clear_queueADestructiveIdempotent
Clear items from the execution queue.
Args:
clear_running: Stop the currently running workflow
clear_pending: Remove pending workflows from the queue
Inputs: clear_pending, clear_running. Returns: result
comfyui_create_workflowARead-onlyIdempotent
Create a ComfyUI workflow from a template with optional parameter overrides.
Available templates: ``txt2img``, ``img2img``, ``upscale``, ``inpaint``,
``txt2vid_animatediff``, ``txt2vid_wan``, ``controlnet_canny``,
``controlnet_depth``, ``controlnet_openpose``, ``ip_adapter``,
``lora_stack``, ``face_restore``, ``flux_txt2img``, ``sdxl_txt2img``.
Args:
template (required): Template name from the list above.
params (optional): JSON string of parameter overrides. Defaults to
an empty string, meaning "use template defaults". Pass either
``""`` or ``"{}"`` for no overrides. Common keys:
``prompt``, ``negative_prompt``, ``width``, ``height``,
``steps``, ``cfg``, ``model``, ``denoise``, ``controlnet_model``,
``control_strength``, ``lora_name``, ``lora_strength``.
Example:
``comfyui_create_workflow(template="txt2img",
params='{"prompt": "a sunset", "width": 768, "steps": 30}')``
Inputs: template (required), params. Returns: object
comfyui_download_modelA
Download a model from HuggingFace or CivitAI via ComfyUI-Model-Manager.
Returns:
JSON with download task status. Use comfyui_get_download_tasks to check progress.
Inputs: url (required), folder (required), filename. Returns: object
comfyui_generate_imageA
Generate an image from a text prompt using a default txt2img workflow.
Inputs: prompt (required), cfg, wait, model, +4 more. Returns: object
comfyui_get_custom_node_statusARead-onlyIdempotent
Check the custom node operation queue status.
Returns:
JSON with queue status: total tasks, completed, in progress, and
whether the queue is currently processing.
Inputs: no named parameters. Returns: object
comfyui_get_download_tasksARead-onlyIdempotent
Check the status of active model downloads.
Returns:
JSON with list of download tasks including progress, speed, and status.
Inputs: no named parameters. Returns: object
comfyui_get_historyARead-onlyIdempotent
Browse ComfyUI execution history (read-only).
Uses server-side `/history?offset=N&max_items=M` so callers can page
arbitrarily far back. The tool requests one extra entry per page so it
can set ``has_more`` without an additional round-trip.
Args:
limit: Maximum number of results to return (default: 25, max: 100)
offset: Zero-based starting index (default: 0)
Returns:
Envelope with keys ``items``, ``count`` (items in this page),
``offset``, ``limit``, ``has_more``, and ``total``.
``total`` is set only when we can prove the true count:
- ``offset + count`` on the last page when ``count > 0``
(the upstream returned at most ``limit`` entries, so we've seen
everything from ``offset`` onward).
- ``0`` when ``offset == 0`` and the upstream returned nothing
(history is genuinely empty).
- ``None`` otherwise (``has_more`` is True, OR we paged past the
end and got back an empty result — in the latter case the true
count is somewhere in ``[0, offset]`` and we can't tell which).
``has_more`` is the canonical end-of-history signal.
Inputs: limit, offset. Returns: object
comfyui_get_imageARead-onlyIdempotent
Download a generated image from ComfyUI or return a direct view URL.
Returns:
Base64-encoded image data with content type prefix, or a direct image URL.
When response_format='data_uri' and preview_format is set, ComfyUI re-encodes
the image server-side as a smaller webp or jpeg thumbnail.
Inputs: filename (required), subfolder, preview_format, preview_quality, +2 more. Returns: result
comfyui_get_jobARead-onlyIdempotent
Look up a single job by prompt_id across queue + history.
Returns a flat unified job object with top-level keys: prompt_id, status
(pending/in_progress/completed/failed/cancelled), timing fields (created_at,
started_at, completed_at, execution_duration), outputs (when completed),
and error (when failed). Use this to check on a job that may be queued,
running, or already finished.
Note: this replaces the previous /history/{prompt_id} envelope shape
(`{prompt_id: {...}}`); callers should index fields directly on the
returned object.
Inputs: prompt_id (required). Returns: object
comfyui_get_model_metadataBRead-onlyIdempotent
Get metadata for a model file.
Args:
folder: Model folder type (checkpoints, loras, vae, etc.)
filename: Name of the model file
Inputs: folder (required), filename (required). Returns: object
comfyui_get_model_presetsARead-onlyIdempotent
Get recommended generation presets for a model family.
The presets are static data baked into this MCP — they reflect
community best-practice defaults, not anything the connected ComfyUI
server reports. At least one of ``model_name`` or ``model_family``
must be supplied; if both are given, ``model_family`` takes
precedence and ``model_name`` is ignored.
Args:
model_name (required if ``model_family`` is omitted): Model
filename to auto-detect the family from (e.g.
``sd_xl_base_1.0.safetensors`` → ``sdxl``). Used as a
fallback when ``model_family`` is empty.
model_family (required if ``model_name`` is omitted): Explicit
family identifier. Valid values: ``sd15``, ``sdxl``,
``flux``, ``sd3``, ``cascade`` (aliases like ``sd1.5``,
``stable-diffusion-xl``, ``flux.1``, ``sd3.5``,
``stable-cascade`` are also accepted).
Returns:
Dict ``{"family": "<id>", "recommended": {<settings>}}`` where
``recommended`` always contains the keys ``sampler`` (str),
``scheduler`` (str), ``steps`` (int), ``cfg`` (float),
``resolution`` (str like ``"1024x1024"``), ``clip_skip`` (int),
and ``notes`` (str). Callers that only need the settings can
read ``result["recommended"]`` directly.
Inputs: model_name, model_family. Returns: object
comfyui_get_node_infoARead-onlyIdempotent
Get the input/output schema and metadata for a single ComfyUI node type.
Returns a dict with keys: input, input_order, is_input_list, output,
output_is_list, output_name, name, display_name, description, python_module,
category, output_node, search_aliases, plus optional flags like deprecated,
experimental, and api_node when set on the node.
Inputs: node_class (required). Returns: object
comfyui_get_progressARead-onlyIdempotent
Get the current execution progress for a workflow via HTTP.
Returns status (queued/running/completed/error/unknown), queue position,
and output files when available. Step progress and current node are only
available when using wait=True on run_workflow/generate_image (WebSocket).
Args:
prompt_id: The prompt_id returned by run_workflow or generate_image.
Inputs: prompt_id (required). Returns: object
comfyui_get_prompting_guideARead-onlyIdempotent
Get the prompting guide for a model family.
The guide is static data baked into this MCP — it gives stylistic
and structural advice tuned to each family (prompt structure,
weighting syntax conventions, recommended quality tags, negative
prompt tips). It does not reflect the connected ComfyUI server's
installed models or state.
Args:
model_family (required): Family identifier. Valid values:
``sd15``, ``sdxl``, ``flux``, ``sd3``, ``cascade`` (aliases
like ``sd1.5``, ``stable-diffusion-xl``, ``flux.1``,
``sd3.5``, ``stable-cascade`` are also accepted).
Returns:
Dict ``{"family": "<id>", "guide": {<advice>}}`` where ``guide``
always contains the keys ``prompt_structure`` (str),
``weight_syntax`` (str), ``quality_tags`` (list[str]), and
``negative_prompt_tips`` (str). Callers that only need the
advice can read ``result["guide"]`` directly.
Inputs: model_family (required). Returns: object
comfyui_get_queueARead-onlyIdempotent
Get the current ComfyUI execution queue state.
Inputs: no named parameters. Returns: object
comfyui_get_queue_statusARead-onlyIdempotent
Get detailed queue status including currently running and pending prompts.
Inputs: no named parameters. Returns: object
comfyui_get_server_featuresARead-onlyIdempotent
Get the feature flags advertised by the ComfyUI server.
Returns the raw ``/features`` response — typically a dict of
{feature_name: bool}. Useful for capability-based branching, e.g.
checking ``supports_preview_metadata`` before requesting preview-format
images via ``comfyui_get_image``.
Inputs: no named parameters. Returns: object
comfyui_get_system_infoARead-onlyIdempotent
Return sanitized ComfyUI system information.
Returns a whitelist-filtered subset of system stats useful for making
generation decisions: GPU VRAM, queue depth, and ComfyUI version.
Sensitive fields (hostname, OS, CPU details, file paths, Python version,
network interfaces) are deliberately excluded.
Returns:
Dictionary with keys: comfyui_version, devices (list of GPU info),
queue (running/pending counts).
Inputs: no named parameters. Returns: object
comfyui_get_workflow_from_imageARead-onlyIdempotent
Extract embedded workflow and prompt metadata from a ComfyUI-generated PNG.
ComfyUI embeds the full workflow JSON and prompt data in PNG text chunks.
This enables extracting the exact settings used to generate an image
for inspection or re-execution.
Args:
filename: Name of the PNG file to extract metadata from
subfolder: Subfolder within ComfyUI's output directory (default: empty)
Returns:
Dict with 'workflow' (parsed JSON or None), 'prompt' (parsed JSON or None),
and 'message' (human-readable status).
Inputs: filename (required), subfolder. Returns: object
comfyui_inpaint_imageA
Inpaint regions of an image using a mask and text prompt.
Both the input image and mask must already be uploaded via
comfyui_upload_image/comfyui_upload_mask.
White regions in the mask indicate areas to regenerate.
Inputs: mask (required), image (required), prompt (required), cfg, +5 more. Returns: object
comfyui_install_custom_nodeA
Install a custom node pack from the ComfyUI Manager registry.
Args:
node_id: Node pack ID from the registry (use search_custom_nodes to find IDs).
version: Specific version to install (empty string = latest).
restart: If True, restart ComfyUI after install and run a security audit
on all installed nodes. If False, manual restart is needed.
Returns:
Status message. If restart=True, includes security audit results.
Inputs: node_id (required), restart, version. Returns: result
comfyui_interruptADestructiveIdempotent
Interrupt the currently executing workflow.
Without prompt_id: global interrupt — stops whatever is running now.
With prompt_id: targeted — only interrupts if that prompt is the
running one. ComfyUI silently no-ops if prompt_id is queued but
not yet running.
Inputs: prompt_id. Returns: result
comfyui_list_extensionsARead-onlyIdempotent
List installed ComfyUI extensions (front-end / back-end JavaScript modules registered with the ComfyUI server).
Returns a paginated envelope: ``{items, total, offset, limit, has_more}``.
Each item is the extension's URL/path string.
Inputs: limit, offset. Returns: object
comfyui_list_jobsARead-onlyIdempotent
List jobs across queue and history with filtering, sorting, and pagination.
Returns {"jobs": [...], "pagination": {"offset", "limit", "total", "has_more"}}.
Each job includes prompt_id, status (pending/in_progress/completed/failed/cancelled),
timing, and outputs (when completed).
Inputs: limit, offset, status, sort_by, +2 more. Returns: object
comfyui_list_model_foldersARead-onlyIdempotent
List the model-folder types ComfyUI recognizes (checkpoints, loras, vae,
controlnet, etc.). Pass any returned name as the folder argument to
comfyui_list_models or comfyui_get_model_metadata.
Returns a paginated envelope: ``{items, total, offset, limit, has_more}``.
Inputs: limit, offset. Returns: object
comfyui_list_modelsARead-onlyIdempotent
List available models in a folder (checkpoints, loras, vae, etc.).
Args:
folder: Model folder type (checkpoints, loras, vae, etc.)
limit: Maximum number of results to return (default: 25, max: 100)
offset: Starting index for pagination (default: 0)
Inputs: limit, folder, offset. Returns: object
comfyui_list_nodesARead-onlyIdempotent
List all available ComfyUI node types.
Args:
limit: Maximum number of results to return (default: 25, max: 100)
offset: Starting index for pagination (default: 0)
Inputs: limit, offset. Returns: object
comfyui_list_outputsARead-onlyIdempotent
List output files from ComfyUI's execution history.
Args:
limit: Maximum number of results to return (default: 25, max: 100)
offset: Starting index for pagination (default: 0)
Returns:
JSON envelope with paginated list of objects with 'filename' and
'subfolder' keys. Pass these values to comfyui_get_image to retrieve files.
Inputs: limit, offset. Returns: object
comfyui_list_workflowsARead-onlyIdempotent
List workflow templates registered on the ComfyUI server (the
/workflow_templates endpoint, populated by installed front-end packages).
This is distinct from ``comfyui_create_workflow``'s built-in template names
(txt2img, img2img, etc.) which are hard-coded in the MCP for graph generation.
Returns a paginated envelope: ``{items, total, offset, limit, has_more}``.
Each item is ``{"package": str, "templates": [...]}`` from the server.
Inputs: limit, offset. Returns: object
comfyui_modify_workflowARead-onlyIdempotent
Apply batch operations to a ComfyUI workflow.
Operations execute sequentially in array order. If any operation fails,
the call raises ``ValueError`` and the input workflow is left
unmodified (atomic — operations are applied to a deep copy).
Args:
workflow (required): JSON string of the workflow to modify.
operations (required): JSON string of an array of operation objects.
Operation reference:
- ``add_node`` — append a new node. Fields:
``{"op": "add_node", "class_type": "<NodeType>",
"node_id": "<id>" (optional, auto-assigned if omitted),
"inputs": {...} (optional default inputs)}``
- ``remove_node`` — drop a node. Fields:
``{"op": "remove_node", "node_id": "<id>"}``
- ``set_input`` — set or replace a single input value. Fields:
``{"op": "set_input", "node_id": "<id>",
"input_name": "<key>", "value": <any>}``
- ``connect`` — wire one node's output into another's input. Fields:
``{"op": "connect", "from_node": "<id>", "from_output": <int>,
"to_node": "<id>", "to_input": "<key>"}``
- ``disconnect`` — clear an existing input connection. Fields:
``{"op": "disconnect", "node_id": "<id>", "input_name": "<key>"}``
Example:
``operations='[{"op": "set_input", "node_id": "3",
"input_name": "steps", "value": 50},
{"op": "add_node", "class_type": "LoraLoader"}]'``
Inputs: workflow (required), operations (required). Returns: object
comfyui_run_workflowA
Submit an arbitrary ComfyUI workflow for execution.
See also: comfyui_run_workflow_stream for a streaming variant that emits
per-node progress events while the workflow executes.
Args:
workflow: JSON string of a ComfyUI workflow (API format).
Each key is a node ID, each value has 'class_type' and 'inputs'.
wait: If True, block until execution completes and return structured result
with status, outputs, and elapsed time. If False (default), return
immediately with just the prompt_id.
Inputs: workflow (required), wait. Returns: object
comfyui_run_workflow_streamA
Submit a ComfyUI workflow and return websocket stream events plus final status.
Uses ComfyUI's websocket stream endpoint internally to capture per-event
execution updates (for example, `progress`, `executing`, `executed`).
Events are filtered by `prompt_id` when that field is present in the
websocket payload.
See also: comfyui_run_workflow for a non-streaming variant. Use this
streaming version when you need real-time per-node progress events
(intended for tooling that surfaces progress to a user); use the
non-streaming variant for fire-and-forget submission or when you only
need the final result.
Args:
workflow: JSON string of a ComfyUI workflow (API format).
Inputs: workflow (required). Returns: object
comfyui_search_custom_nodesARead-onlyIdempotent
Search installed custom node packs by name, description, or author.
Args:
query: Search term to match against installed node pack metadata.
limit: Maximum number of results to return (default: 10, max: 25)
offset: Starting index for pagination (default: 0)
Returns:
JSON with matching node packs including name, description, author,
install status, version, and ID.
Inputs: query (required), limit, offset. Returns: object
comfyui_search_modelsARead-onlyIdempotent
Search for models on HuggingFace or CivitAI.
Returns:
JSON with search results including name, download URL, size, and stats.
Use comfyui_download_model with the URL to install a model.
Inputs: query (required), limit, offset, source, +1 more. Returns: object
comfyui_summarize_workflowARead-onlyIdempotent
Summarize a ComfyUI workflow's structure, data flow, and key parameters.
Parses the workflow graph, extracts models, parameters, and execution flow. Enriches with display names from the ComfyUI server when available.
Inputs: workflow (required), output_format. Returns: result
comfyui_transform_imageA
Transform an existing image using a text prompt (img2img).
The input image must already be uploaded to ComfyUI via comfyui_upload_image.
Inputs: image (required), prompt (required), cfg, wait, +4 more. Returns: object
comfyui_uninstall_custom_nodeADestructive
Uninstall a custom node pack.
Args:
node_id: Node pack ID to uninstall.
restart: If True, restart ComfyUI after uninstall.
Returns:
Status message.
Inputs: node_id (required), restart. Returns: result
comfyui_update_custom_nodeA
Update a custom node pack to the latest version.
Args:
node_id: Node pack ID to update.
restart: If True, restart ComfyUI after update and run a security audit
on all installed nodes.
Returns:
Status message. If restart=True, includes security audit results.
Inputs: node_id (required), restart. Returns: result
comfyui_upload_imageA
Upload an image to ComfyUI.
Defaults to ComfyUI's input directory (the destination workflows read from). Set destination='output' or 'temp' only if you have a specific reason.
Inputs: filename (required), image_data (required), overwrite, subfolder, +1 more. Returns: result
comfyui_upload_maskA
Upload a mask image to ComfyUI.
The mask's alpha channel is merged into the original image's alpha channel by the ComfyUI server. The original image must already exist in ComfyUI. Defaults to ComfyUI's input directory.
Inputs: filename (required), mask_data (required), original_image (required), overwrite, +3 more. Returns: result
comfyui_upscale_imageA
Upscale an image using a model-based upscaler.
The input image must already be uploaded to ComfyUI via comfyui_upload_image.
The scale factor is determined by the upscale model (e.g. RealESRGAN_x4plus = 4x).
Inputs: image (required), wait, upscale_model. Returns: object
comfyui_validate_workflowARead-onlyIdempotent
Validate a ComfyUI workflow for structural correctness and security.
Checks: node structure, connection references, installed node types,
available models, dangerous nodes, and suspicious inputs.
Args:
workflow (required): JSON string of the workflow to validate.
Returns:
Dict with keys:
- ``valid`` (bool): True only if there are zero entries in ``errors``.
- ``errors`` (list[str]): blocking issues — invalid structure,
connections that reference nonexistent nodes, ``class_type``
not installed on the connected server, missing required
inputs, security blocks, etc. Each entry is a human-readable
string identifying the offending node id and what's wrong.
- ``warnings`` (list[str]): non-blocking concerns — missing model
files, dangerous node names, suspicious input patterns
(e.g. ``__import__``), or a server-unreachable note when the
installed-class_type check has to be skipped.
- ``node_count`` (int): number of nodes in the workflow.
- ``pipeline`` (str): coarse type — one of ``txt2img``,
``img2img``, ``upscale``, ``img2img -> upscale``,
``txt2img -> upscale``, or ``unknown``. (For the full
structural breakdown, use ``comfyui_analyze_workflow``.)
Inputs: workflow (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
There are several overlapping tool pairs, notably comfyui_get_queue vs comfyui_get_queue_status, and comfyui_get_history vs comfyui_list_jobs vs comfyui_get_job. The descriptions are detailed and cross-referenced, so the boundaries are clear on close reading, but an agent could easily misselect between these similar-purpose tools.
Every tool uses the consistent comfyui_ prefix followed by a snake_case verb_noun pattern (list_models, create_workflow, cancel_job). No mixed camelCase or irregular verb usage; parallel operations share the same verb (get_, list_, run_, upload_), making the naming predictable and easy to navigate.
At 46 tools, the set is well above the 25+ threshold where it becomes hard to discover and choose among options. While each tool is individually purposeful, the surface could be consolidated—for example, merging queue-status variants and unifying history/job listing—to make the server more manageable.
The tool set provides broad coverage of the ComfyUI domain: workflow creation/validation/modification/execution, image manipulation (transform, inpaint, upscale), model and custom-node management, and queue/job lifecycle control. Minor gaps like deleting models/images or retrying failed jobs exist but are easily worked around.
Maintenance
Related MCP Connectors
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for ComfyUI — text-to-image, variations, img2img refine, upscale, image proxy, and workflow runner.15145 npm3MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that connects local ComfyUI to AI agents, enabling natural language control of ComfyUI for creating workflows, generating images, and managing the queue.1-
- AlicenseBqualityCmaintenanceAn MCP server that bridges AI agents with ComfyUI for automated workflow building, execution, monitoring, and output routing.961MIT
- AlicenseAqualityBmaintenanceAn MCP server that integrates with a local ComfyUI, allowing assistants to list and run workflows, monitor progress, and view results, as well as read and edit the live workflow canvas via an optional bridge node.6416GPL 3.0