comfyui-automation

Drive a local ComfyUI server headlessly — submit workflows, poll the queue, download outputs, write prompts. Three transports (HTTP, CLI, MCP) share the same primitives.

What this is

A reusable Skill (AgentSkills format) for anyone who needs to run ComfyUI from scripts, agents, or MCP clients — without opening the GUI.

Three transports, one set of primitives:

Transport	Use when
HTTP API	curl, scripts in any language, ad-hoc debugging
Python CLI (cli-anything-comfyui)	Python scripts, shell pipelines
MCP server	Claude / Cursor / OpenClaw agents

Pick by caller, not by task.

What's in here

• SKILL.md — main entry point. Read this first.
• references/ — focused deep-dives:
  • workflow-json.md — workflow format, edit patterns, version-migration gotchas
  • launch-flags.md — flags that prevent 80% of headless failures
  • prompt-engineering.md — three rules that cover 90% of cases
  • debug-checklist.md — 5 black-screen causes, keyword → fix map
  • comfyui-mcp.md — four open-source MCP servers compared
• scripts/ — drop-in Python:
  • submit_workflow.py — submit → poll → download, one call
  • check_status.py — server + GPU + queue health snapshot

Quick start

HTTP (curl)

# Submit a workflow
curl -s -X POST http://127.0.0.1:8188/prompt \
  -H 'Content-Type: application/json' \
  -d @workflow.json

# Poll for completion
curl -s http://127.0.0.1:8188/history/<prompt_id>

Python CLI

pip install -e /path/to/CLI-Anything/comfyui/agent-harness   # one-time

cli-anything-comfyui --url http://127.0.0.1:8188 system stats
cli-anything-comfyui --url http://127.0.0.1:8188 --json models checkpoints
cli-anything-comfyui --url http://127.0.0.1:8188 queue status

Drop-in Python (no install)

# Health check
python scripts/check_status.py

# Submit a workflow with prompt + seed override
python scripts/submit_workflow.py workflow.json \
  --set 6.text="a mountain at sunset" \
  --set 3.seed=42 \
  --out ./outputs

MCP

Pick a server from references/comfyui-mcp.md and add to your agent's MCP config. Most popular: 0xhackerfren/Comfy-UI-MCP (57 tools, 14 templates).

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp-server"],
      "env": { "COMFYUI_URL": "http://127.0.0.1:8188" }
    }
  }
}

Server-side setup (one-time)

Start ComfyUI with flags that prevent 80% of headless failures:

python main.py \
  --listen 0.0.0.0 \
  --port 8188 \
  --disable-dynamic-vram \
  --lowvram \
  --preview-method auto \
  --cpu-vae

Why each flag → references/launch-flags.md.

Philosophy

• Same primitives, three transports. No transport-specific abstractions in the Skill.
• Environment-agnostic. No absolute paths; everything uses <COMFYUI_URL>.
• Experience > theory. Documented failure modes and the flag that prevents each.
• Lean SKILL.md. Deep content lives in references/ and loads only when triggered.

License

Apache-2.0. See LICENSE.