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-only review subagent, a /preflight command, 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:

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://settings
• Prompts: 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) via Depends() providers (auto-excluded from the MCP schema) instead of receiving them through register_*_tools() factories. history_di.py is 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-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 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": "<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-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 << 'EOF'
comfyui:
  url: "http://127.0.0.1:8188"
EOF

For a remote server:

cat > ~/.comfyui-mcp/config.yaml << 'EOF'
comfyui:
  url: "https://your-gpu-server:8188"
EOF

Add 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.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.

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 — wires context7 (MCP/FastMCP/Pydantic/httpx docs), a review subagent, a /preflight command, the graphify plugin, and a watcher.ignore
• .opencode/rules/ — path-scoped constitutional rules (security, architecture, tools, testing, workflow, enforcement, graphify); loaded as instructions in opencode.json
• .opencode/agents/review.md — read-only pre-PR reviewer subagent
• .opencode/commands/preflight.md — /preflight command (lint/format/type/tests gate)
• .opencode/hooks/check-no-skipped-tests.sh — zero-skip suite-health gate
• .opencode/plugins/graphify.js — knowledge-graph reminder plugin
• skills/ — 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.

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:

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 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..."], 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 --help

Tools

Generation & Workflows

Job Management

Discovery

Custom Node Management

Requires: ComfyUI-Manager available on the target ComfyUI server. If unavailable, node-management tools return a helpful error.

History

Model Search & Download

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_models works without it.

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

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.

Prompts

Reusable, parameterized prompt recipes for the built-in workflow templates. Return a plain string the LLM can use as guidance.

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
• /history POST — 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: 8080

When 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:

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:

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 audit

Enforce 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

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(), subprocess in 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 injection
• Allowlist-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)
• SecurityMiddleware centralizes rate-limit checks + entry audit logging across every tool call (FastMCP 4 on_call_tool hook), so the per-tool limiter.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 written
• mask_error_details=True on the server constructor masks internal exception tracebacks from clients — only ToolError messages (which we control) include details
• Built-in FastMCP 4 middleware wired alongside SecurityMiddleware (see build_middleware_stack()): ResponseCachingMiddleware (caches read-only tools + the 4 comfyui:// resources, 30s TTL), ResponseLimitingMiddleware (caps list_nodes/list_models/get_history payloads 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_load only, 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 scalable

Env 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--> CWS

Components

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 -v

Evaluation

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/phase5

Run 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-model

Compare 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-after

Each 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.0

The 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:8188

The 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:latest

How 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-secure

Linux users: Add --add-host=host.docker.internal:host-gateway if using host.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-secure

The 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 works
• Mount your config: -v ~/.comfyui-mcp:/home/app/.comfyui-mcp:ro
• Set COMFYUI_URL to reach your ComfyUI instance from inside the container
• Use host.docker.internal to reach ComfyUI running on your host machine
• The GHCR image (ghcr.io/hybridindie/comfyui_mcp:latest) means no local build needed

License

MIT