comfyui-mcp

MCP-Server für ComfyUI. Generieren Sie Bilder aus natürlichsprachlichen Prompts mit jedem MCP-kompatiblen Client.

Teil der MCP Server Series.

Status

v0.2 — Kern-Tools plus Upscaling, Bild-Proxy und Unterstützung für öffentliche URLs. Tools: generate_image, generate_variations, generate_with_workflow, refine_image, upscale_image, list_models, list_workflows, upload_image. Siehe Roadmap für kommende Funktionen.

Installation

npx (keine Installation erforderlich)

npx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188

npm

npm install -g @miller-joe/comfyui-mcp
comfyui-mcp --comfyui-url http://your-comfyui-host:8188

Docker

docker run -p 9100:9100 \
  -e COMFYUI_URL=http://your-comfyui-host:8188 \
  ghcr.io/miller-joe/comfyui-mcp:latest

Verbinden eines MCP-Clients

Beispiel — Claude Code:

claude mcp add --transport http comfyui http://localhost:9100/mcp

Oder registrieren Sie den streamfähigen HTTP-Endpunkt bei einem MCP-Gateway (z. B. MetaMCP), um ihn mit anderen Servern zu aggregieren.

Konfiguration

Alle Optionen können über CLI-Flags oder Umgebungsvariablen festgelegt werden:

An Clients zurückgegebene Bild-URLs

Generierungs-Tools geben Bild-URLs wie <comfyui-public-url>/view?filename=… zurück. Wenn --comfyui-public-url nicht gesetzt ist, verwenden die URLs den internen --comfyui-url-Wert.

Der Server stellt außerdem einen Proxy-Endpunkt bereit: GET /images/<filename>?subfolder=&type=output streamt die Bildbytes durch den MCP-Server — nützlich, wenn Clients den MCP-Server erreichen können, aber nicht direkt ComfyUI.

Der Standard-Checkpoint muss mit einer Datei übereinstimmen, die in Ihrem ComfyUI-Verzeichnis models/checkpoints/ installiert ist. Überschreiben Sie dies über COMFYUI_DEFAULT_CKPT oder übergeben Sie checkpoint als Tool-Argument.

Tools

generate_image

Generiert ein Bild aus einem Text-Prompt unter Verwendung des Standard-txt2img-Workflows von ComfyUI.

Parameter: prompt (erforderlich), negative_prompt, width, height, steps, cfg, seed, checkpoint.

generate_variations

Generiert mehrere Variationen desselben Prompts durch Variieren des Seeds. Gibt alle Bilder gleichzeitig zurück.

Parameter: prompt (erforderlich), count (2–16, Standard 4), plus die gleichen Generierungsparameter wie bei generate_image, mit base_seed anstelle von seed.

generate_with_workflow

Übermittelt ein beliebiges ComfyUI-Workflow-JSON (vollständiger Knotengraph) und gibt die resultierenden Bild-URLs zurück. Verwenden Sie dies für benutzerdefinierte Workflows — ControlNet, Upscaling oder alles, was aus dem Save (API Format) von ComfyUI exportiert wurde.

Parameter: workflow (Objekt) — der vollständige Knotengraph.

refine_image

Führt img2img auf einem Quellbild aus: ruft eine Quell-URL ab, lädt sie in ComfyUI hoch und führt einen Denoising-Durchgang aus, der von einem neuen Prompt geleitet wird. Ein niedrigerer denoise-Wert bewahrt mehr vom Original; ein höherer gibt dem Prompt mehr Freiheit.

Parameter: prompt, source_image_url (erforderlich), denoise (0–1, Standard 0.5), plus Standard-Generierungsparameter.

list_models

Listet verfügbare Checkpoints, LoRAs, Sampler oder Scheduler auf der ComfyUI-Instanz auf.

Parameter: kind — einer der Werte checkpoints (Standard), loras, samplers, schedulers.

list_workflows

Listet integrierte Workflow-Vorlagen auf, die mit diesem Server geliefert werden (derzeit txt2img, img2img).

upload_image

Lädt ein Referenzbild in ComfyUI hoch, um es in img2img-, ControlNet- oder IP-Adapter-Workflows zu verwenden.

Parameter: source_url oder image_base64 (eines erforderlich), filename (optional), overwrite (Standard false).

Rückgabe: der gespeicherte Dateiname, der als image-Eingabe in Workflow-Knoten wie LoadImage verwendet werden kann.

generate_with_controlnet

Generiert ein Bild, das durch ein von ControlNet vorverarbeitetes Bild (Pose-Skelett, Tiefenkarte, Canny-Kanten, Normalkarte usw.) sowie einen Text-Prompt konditioniert wird.

Parameter: prompt, control_image_url (das vorverarbeitete Konditionierungsbild — dieses Tool führt keine Vorprozessoren aus), controlnet_model (Dateiname aus models/controlnet/), strength (0–2, Standard 1), start_percent / end_percent (0–1, wann CN während des Samplings aktiv ist), plus Standard-Generierungsparameter.

Erfordert ein ControlNet-Modell, das in Ihrem ComfyUI-Verzeichnis models/controlnet/ installiert ist.

generate_with_ip_adapter

Generiert ein Bild unter Verwendung eines Referenzbildes als visueller/Stil-/Subjekt-Leitfaden via IP-Adapter.

Parameter: prompt, reference_image_url, preset (z. B. "STANDARD (medium strength)", "PLUS FACE (portraits)", "VIT-G (medium strength)"), weight (0–3, Standard 1), start_at / end_at (0–1), plus Standard-Generierungsparameter.

Erfordert das ComfyUI-IPAdapter-plus Custom-Node-Paket sowie die passenden IPAdapter-Gewichte und CLIP-Vision-Modelle für das Preset.

Workflow-Vorlagen-Registry

Speichern Sie komplexe Workflow-JSONs einmal und führen Sie sie später per Namen aus. Vorlagen werden auf der Festplatte unter --templates-dir gespeichert (Standard: ~/.config/comfyui-mcp/templates/<name>.json), sodass sie Neustarts überstehen und über MCP-Clients hinweg portabel sind.

Vorlagennamen müssen alphanumerisch beginnen; a-z, A-Z, 0-9, -, _; max. 64 Zeichen.

Rückgabeformat

Alle Generierungs-Tools geben Bild-URLs zurück, die direkt von der ComfyUI-Instanz bereitgestellt werden (http://<comfyui>/view?filename=…). Diese URLs können direkt an jeden Client weitergegeben werden, der Bild-URLs akzeptiert.

Architektur

┌────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │
│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │
└────────────────┘     └──────────────────┘     └──────────────┘
     streamable HTTP        HTTP REST + poll

Der Server ist zustandslos. Eine einzelne MCP-Anfrage → Workflow an ComfyUI übermitteln → /history/{id} abfragen, bis er abgeschlossen ist → Bild-URLs zurückgeben.

Entwicklung

git clone https://github.com/miller-joe/comfyui-mcp
cd comfyui-mcp
npm install
npm run dev       # hot-reload via tsx watch
npm run build     # compile TS to dist/
npm run typecheck # strict type checking

Erfordert Node 20+.

Roadmap

• [x] generate_image — Text-zu-Bild mit Standard-Workflow

• [x] generate_with_workflow — beliebige Workflows übermitteln

• [x] list_models / list_workflows

• [x] upload_image — Referenzbilder für img2img / ControlNet / IP-Adapter

• [x] generate_variations — Batch-Variationen eines Prompts

• [x] refine_image — img2img-Verfeinerung von einer Quell-URL

• [x] upscale_image — Upscale mit ESRGAN/SwinIR-Modellen

• [x] Bild-Proxy-Endpunkt (/images/<filename>) für Clients, die ComfyUI nicht erreichen können

• [x] Konfigurierbare öffentliche URL für extern korrekte Bild-URLs

• [x] Workflow-Vorlagen-Registry: save_workflow_template, list_workflow_templates, get_workflow_template, delete_workflow_template, run_workflow_template

• [x] ControlNet-Workflow-Helfer: generate_with_controlnet (erfordert ControlNet-Modelle auf der ComfyUI-Seite)

• [x] IP-Adapter-Workflow-Helfer: generate_with_ip_adapter (erfordert ComfyUI-IPAdapter-plus-Paket)

• [ ] WebSocket-Fortschrittsereignisse für lang laufende Generierungen

Lizenz

MIT © Joe Miller

Support

Wenn dieses Tool Ihnen Zeit spart, ziehen Sie eine Unterstützung der Entwicklung in Betracht:

Jeder Beitrag finanziert Wartung, Dokumentation und die nächste Veröffentlichung in der MCP Server Series.