Comfyui Mcp

comfyui-mcp-secure

A secure MCP (Model Context Protocol) server for ComfyUI. Enables AI assistants like Claude to generate images, run workflows, and manage jobs through ComfyUI — with built-in security controls that existing ComfyUI MCP servers lack.

> Using Claude? This repo also ships as a Claude Code plugin — 8 /comfy:* slash commands (/comfy:gen, /comfy:workflow, /comfy:troubleshooting, …) and a PostToolUse security hook, all pre-wired to the MCP server. One command to install: claude plugin install . See [Install as a Claude plugin](#what-the-plugin-gives-you) for the full reference + worked end-to-end example.

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 (eval, exec, __import__, subprocess). Configurable audit-only or enforcement mode. | | Path Sanitizer | Validates all filenames, subfolders, and URL path segments — blocks path traversal (../), null bytes, percent-encoded attacks, absolute paths, and disallowed file extensions. | | Rate Limiter | Token-bucket rate limiting per tool category to prevent runaway loops. | | 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 (/userdata, /free, /users) are never proxied. /system_stats is called internally by comfyui_get_system_info but only a strict whitelist (GPU VRAM, queue counts, version) is returned. |

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-4096 appear in the tool's JSON schema
• Output schemas: 26 tools return structured data with auto-generated outputSchema, enabling clients to parse responses without guessing the shape
• Streamable HTTP transport: Optional remote transport via transport.remote.enabled using the MCP spec's recommended Streamable HTTP protocol

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](CHANGELOG.md) 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 to text or mermaid via a Pydantic Literal.

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 to items: [{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": "",
  "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

> Claude Code users: the fastest path is the plugin — see [Install as a Claude plugin](#install-as-a-claude-plugin-from-this-repo) below. It wires the MCP server + slash commands + security hook in one step. The options below are for everyone else (raw MCP wiring, Docker, source installs).

Option A: From PyPI

pip install comfyui-mcp-secure

For an isolated CLI install, use one of:

uv tool install comfyui-mcp-secure
pipx install comfyui-mcp-secure

For a one-shot run without installing first:

uvx comfyui-mcp-secure --help

Option B: From source (recommended for development)

git clone https://github.com/hybridindie/comfyui_mcp.git
cd comfyui_mcp
uv sync

Option C: Docker (no clone required)

docker pull ghcr.io/hybridindie/comfyui_mcp:latest

Or 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  ~/.comfyui-mcp/config.yaml  **Note:** `host.docker.internal` routes 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`.

### Install as a Claude plugin (from this repo)

This repository ships as a complete Claude Code plugin — manifest at `.claude-plugin/plugin.json`. Two install paths:

```bash
# Direct from GitHub (recommended — pulls the published tag):
claude plugin install https://github.com/hybridindie/comfyui_mcp

# Or from a local clone (for development or unreleased changes):
claude plugin install .

Plugin-related files in this repo:

• .claude-plugin/plugin.json (plugin manifest — name, version, license, homepage)
• .mcp.json (MCP server bootstrap config)
• hooks/ (security warning hook)
• skills/ (slash-command skills)

If you use the included .mcp.json, set both internal and optional external ComfyUI URLs as needed:

{
  "mcpServers": {
    "comfyui": {
      "command": "uvx",
      "args": ["comfyui-mcp-secure"],
      "env": {
        "COMFYUI_URL": "http://comfyui:8188",
        "COMFYUI_EXTERNAL_URL": "https://comfyui.example.com"
      }
    }
  }
}

What the plugin gives you

Three cooperating layers, used together:

1. MCP tool surface — 47 tools exposing ComfyUI's workflow / generation / discovery / security API. The full table is in the [Tools](#tools) section below — these are the lowest-level primitives, available to any model connected to the server.
2. Slash-command skills under /comfy:* — pre-authored recipes that wrap common multi-tool flows so a user doesn't have to choreograph the calls themselves. Skills load lazily; the two "knowledge" skills (workflows, troubleshooting) get auto-applied by Claude when the conversation matches their topic.
3. PostToolUse security hook — fires after the MCP tools that touch dangerous surface and surfaces a one-line warning if the workflow inspector or node auditor flagged anything.

Slash-command reference

| Command | What it does | |---|---| | /comfy:gen | Generate an image. Picks a model via comfyui_list_models, calls comfyui_generate_image(wait=True), fetches the result via comfyui_get_image. | | /comfy:workflow | Build a workflow from a built-in template, validate it, then offer to run or modify. | | /comfy:workflows | 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. | | /comfy:status | Show queue state (running + pending jobs). | | /comfy:progress | Per-job execution progress (current node, step X of Y, status). | | /comfy:history | Recent completions with prompt IDs and output filenames. | | /comfy:models [folder] | List models in a folder type (defaults to checkpoints). | | /comfy:troubleshooting | 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 hook

A single PostToolUse hook (hooks/security-warning.sh, wired via hooks/hooks.json) fires after these MCP tools:

• comfyui_audit_dangerous_nodes
• comfyui_install_custom_node
• comfyui_update_custom_node
• comfyui_run_workflow
• comfyui_generate_image

It scans the tool output for WorkflowInspector markers ("Dangerous node type", "Suspicious input") and NodeAuditor results with dangerous.count > 0. If anything matches, it prints a one-line warning so Claude sees it and asks the user to confirm before proceeding. The hook always exits 0 — it never blocks; it just adds a heads-up.

End-to-end example

A user types /comfy:gen a yellow apple, photorealistic, 4k. The layers cooperate:

1. The gen skill parses the prompt and applies defaults (512×512, 20 steps, cfg 7.0).
2. It calls comfyui_list_models(folder="checkpoints"), picks an available model from the paginated items list, and confirms with the user if ambiguous.
3. It calls comfyui_generate_image(prompt=..., model=..., wait=True).
4. 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.
5. ComfyUI executes; the tool blocks until the unified envelope comes back with status="completed".
6. The PostToolUse hook fires, checks the tool output for the threat patterns, finds none, and exits silently.
7. The skill reads result["outputs"][0] (a {node_id, filename, subfolder} dict), calls comfyui_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..."], the hook detects the pattern in step 6, and surfaces:

SECURITY: Dangerous node patterns detected. Review the audit results above before proceeding.

Claude sees this in its context 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 --help

Tools

Generation & Workflows

| Tool | Description | |------|-------------| | comfyui_generate_image | Text-to-image using a built-in workflow. Params: prompt, negativeprompt, width, height, steps, cfg, model. Set wait=True to block until complete and return outputs. | | comfyui_transform_image | Image-to-image transformation. Params: image (filename), prompt, negativeprompt, strength (0.0-1.0), steps, cfg, model. Input must be uploaded via comfyui_upload_image first. | | comfyui_inpaint_image | Inpaint masked regions of an image. Params: image, mask (filenames), prompt, negativeprompt, strength, steps, cfg, model. Both files must be uploaded first. | | comfyui_upscale_image | Upscale an image using a model-based upscaler. Params: image (filename), upscalemodel (default: RealESRGANx4plus.pth). | | comfyui_run_workflow | Submit arbitrary ComfyUI workflow JSON. Inspected for dangerous nodes before execution. Set wait=True to block until complete and return outputs. | | comfyui_run_workflow_stream | Submit workflow JSON and capture ComfyUI websocket stream events (progress, executing, executed, etc.) until terminal status, returning events plus final outputs/status. | | comfyui_summarize_workflow | Summarize a workflow's structure, data flow, models, and parameters. Supports output_format="text" (default) or output_format="mermaid" for diagram markup. | | comfyui_create_workflow | Create a workflow from templates including txt2img/img2img/upscale/inpaint, txt2vidanimatediff/txt2vidwan, controlnetcanny/controlnetdepth/controlnetopenpose, ipadapter, lorastack, facerestore, fluxtxt2img, and sdxltxt2img. | | comfyui_modify_workflow | Apply batch operations (addnode, removenode, setinput, connect, disconnect) to a workflow. | | comfyui_analyze_workflow | Return a structured analysis of a workflow as a dict (node_count, class_types, flow, models, parameters, pipeline, prompt_nodes, negative_nodes). Use this when you want to read fields like pipeline programmatically; use comfyui_summarize_workflow for a human-readable text or Mermaid rendering. | | comfyui_validate_workflow | Validate workflow structure, server compatibility, and security. |

Job Management

| Tool | Description | |------|-------------| | comfyui_get_queue | Get current execution queue state. | | comfyui_list_jobs | List jobs across queue + history with status filter, sorting, and pagination. | | comfyui_get_job | Look up a single job (queued/running/finished) by promptid. | | comfyui_cancel_job | Cancel a running or queued job. | | comfyui_interrupt | Interrupt the running workflow (global, or targeted via optional promptid). | | comfyui_get_queue_status | Get detailed queue status including running and pending prompts. | | comfyui_clear_queue | Clear pending and/or running items from the queue. | | comfyui_get_progress | Get execution progress for a workflow by prompt_id. Returns status, queue position, and outputs. |

Discovery

| Tool | Description | |------|-------------| | comfyui_list_models | List available models by folder (checkpoints, loras, vae, etc.). | | comfyui_list_nodes | List all available node types. | | comfyui_get_node_info | Get detailed info about a specific node type. | | comfyui_list_workflows | List saved workflow templates. | | comfyui_list_extensions | List available ComfyUI extensions. | | comfyui_get_server_features | Get ComfyUI server features and capa

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hybridindie
• Source: hybridindie/comfyui_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.