██████╗ ██████╗ ███╗   ███╗███████╗██╗   ██╗██████╗ ██╗██╗      ██████╗ ████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚██╗ ██╔╝██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝
██║     ██║   ██║██╔████╔██║█████╗   ╚████╔╝ ██████╔╝██║██║     ██║   ██║   ██║
██║     ██║   ██║██║╚██╔╝██║██╔══╝    ╚██╔╝  ██╔═══╝ ██║██║     ██║   ██║   ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║██║        ██║   ██║     ██║███████╗╚██████╔╝   ██║
 ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝   ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝

ComfyPilot v1.9.0

ComfyPilot ist ein MCP-Server für ComfyUI. Er bietet einem KI-Agenten eine saubere Werkzeugoberfläche für Workflow-Erstellung, Warteschlangenverwaltung, Fortschrittsüberwachung, Bildabruf, Schnappschüsse und VRAM-Sicherheit.

Dokumentation

• Produktionshandbuch: docs/MANUAL.md

• ComfyUI-Release-Kompatibilitätsprüfung: docs/COMFYUI_COMPATIBILITY.md

• Versionshinweise: CHANGELOG.md

Related MCP server: ComfyUI MCP

Was dies ist

• Eine praktische Brücke zwischen KI-Agenten und ComfyUI.

• Eine MCP-Oberfläche mit 96 Werkzeugen für Workflow-Erstellung, moderne Auftragsprüfung/-stornierung, Modellverwaltung, Bild-Upload/-Download, Verlauf, Überwachung, Schnappschüsse, Technikspeicher, VRAM-Sicherheit, Ausgabe-Routing, Blaupausen, Mermaid-Visualisierung, PNG-Import, n-dimensionale Parametersweeps, Partner-API-Erkennung, Modell-Hub-Suche, Desktop-bewusste Instanzsteuerung, generische Artefakte, comfy-env-Worker, comfy-cli-Lebenszyklus und Diagnose.

• Live-Erkennung von Modellordnern: diffusion_models/, text_encoders/, clip_vision/, style_models/, gligen/ (und jeder andere Ordner, den das verbundene ComfyUI tatsächlich bereitstellt) werden standardmäßig durchsucht – keine Checkpoint-zentrierten blinden Flecken mehr.

• Eine workfloworientierte Schleife, die für Iteration gebaut ist, nicht für einmaliges Raten.

• Eine kleine Technikbibliothek zum Speichern und Wiederverwenden funktionierender Muster.

Kern-Denkmodell (Wie man mit diesem MCP denkt)

Verwenden Sie diese Schleife für jede nicht-triviale Aufgabe:

1. System zuerst prüfen – GPU-Zustand lesen, bevor Modelle geladen werden. Beginnen Sie mit comfy_get_system_stats, comfy_check_vram.

2. Technikspeicher prüfen – Bevor Sie von Grund auf neu bauen, verwenden Sie comfy_search_techniques, um zu prüfen, ob ein ähnlicher Workflow bereits in der Bibliothek vorhanden ist.

3. In kleinen Schritten bauen – Verwenden Sie comfy_build_workflow für jede Absicht (txt2img, img2img, upscale, inpaint, controlnet, txt2video, img2video, image2_3d, txt2music, super_resolution, interpolate_frames, segment, train_lora, txt2audio). Bei familiengeführten Absichten wird die Familie automatisch aus dem installierten Checkpoint erkannt; familienunabhängige Absichten (super_resolution, interpolate_frames, segment, train_lora, txt2audio) werden unabhängig vom Checkpoint anhand des Absichtsnamens weitergeleitet. Für gängige Rezepte starten Sie mit comfy_insert_blueprint(name="flux2-txt2img") oder einer der 13 mitgelieferten Blaupausen. Validieren Sie mit comfy_validate_workflow, bevor Sie in die Warteschlange einreihen (6-stufig: Schema, Katalog, Graph, Anti-Zyklus, Umgebung, Ausführungsrisiko).

4. Überwachen und abrufen – Reihen Sie mit comfy_queue_prompt in die Warteschlange ein, beobachten Sie mit comfy_watch_progress, rufen Sie mit comfy_get_output_image ab (gibt Bildinhaltsblöcke direkt im Chat zurück).

5. Schnappschuss vor Änderungen – Führen Sie immer comfy_snapshot_workflow aus, bevor Sie einen funktionierenden Workflow ändern. Verwenden Sie comfy_diff_snapshots und comfy_restore_snapshot zum Rückgängigmachen.

6. Ausgaben weiterleiten – Senden Sie erzeugte Bilder mit comfy_send_to_disk, comfy_send_to_td, comfy_send_to_blender an die Festplatte, an TouchDesigner oder an Blender.

Werkzeugübersicht (96 Werkzeuge)

1) System + GPU

Für Verbindungsstatus, GPU-Diagnose und VRAM-Verwaltung.

• comfy_get_system_stats, comfy_get_gpu_info, comfy_get_features

• comfy_list_extensions, comfy_restart, comfy_free_vram

2) Modelle

Zum Entdecken und Verwalten aller Modelldateien, die ComfyUI bereitstellt. Die Ordner-Taxonomie wird live von /models ermittelt, sodass moderne Familien, deren Gewichte unter diffusion_models/, text_encoders/, clip_vision/, style_models/ oder gligen/ liegen, standardmäßig abgedeckt sind.

• comfy_list_models – Paginierte Auflistung innerhalb eines einzelnen Ordners (folder, limit, offset).

• comfy_get_model_info – Normalisiertes Knotenschema für eine Modelllade-Knotenklasse.

• comfy_list_model_folders – Live-Ordnerliste von GET /models, mit Fallback auf eine statische Standardliste von 16 Ordnern, wenn der Endpunkt nicht erreichbar ist. Meldet source: live | fallback.

• comfy_search_models – Durchsucht standardmäßig jeden erkannten Ordner. Übergeben Sie folders=["checkpoints", "loras"], um einzugrenzen. Eine leere Abfrage gibt ein vollständiges Inventar zurück.

• comfy_refresh_models – Ruft den Cache für jeden Ordner erneut ab; gibt Anzahl pro Ordner + eine total_models-Zahl zurück.

3) Workflow-Ausführung

Zum Einreihen in die Warteschlange, Abbrechen und Verwalten der Prompt-Ausführung.

• comfy_queue_prompt, comfy_get_queue, comfy_cancel_run

• comfy_list_jobs, comfy_get_job, comfy_cancel_jobs

• comfy_interrupt, `comfy_clear_queue

• comfy_extract_schema - Workflow-weit steuerbare Parameter + Abhängigkeitsübersicht (Parameterliste, Modellabhängigkeiten, Embedding-Referenzen, Ausgabeknoten, mit summary_only-Modus).

• comfy_fetch_logs - Nur den Fehler-Traceback + die Liste der abgeschlossenen Knoten aus /history/{prompt_id} extrahieren — behandelt sowohl status.exec_info.errors als auch status.messages-Formen.

• comfy_inspect_workflow - Vertrauensprüfung: Jede class_type als stock / custom klassifizieren und Warnungen anzeigen, bevor nicht vertrauenswürdige Workflows in die Warteschlange gestellt werden.

• comfy_recommend_runtime - Hardware-Urteil (ok / marginal / cloud) + das richtige comfy-cli-Installationsflag für diese Hardware.

• comfy_suggest_timeout - Pro-Workflow-HTTP-Timeout-Vorschlag basierend auf langlaufenden Ausgabeklassen (Standard 300s, bis zu 3600s für Training).

19) Komfort (v1.8.0)

Verwenden Sie dies, um mehrstufige Abläufe zu komprimieren, die ein Agent sonst manuell skripten würde.

• comfy_install_workflow_deps - Automatisch jedes fehlende Custom-Node-Paket installieren, auf das der Workflow verweist (umhüllt comfy node install-deps --workflow).

• comfy_run_with_inputs - Lokale Bilder hochladen + als Workflow-Eingaben einfügen + in die Warteschlange stellen – fasst den dreistufigen img2img-/Inpaint-Ablauf in einem Aufruf zusammen.

• comfy_randomize_seeds - Ersetzt seed=-1-Sentinel-Werte durch kryptografisch sichere zufällige uint32-Werte; force=True randomisiert jedes Seed-Widget.

20) Desktop-Instanz + Artefakte + Worker

Verwenden Sie dies, um die exakte verbundene Desktop-Installation zu steuern, anstatt einen Arbeitsbereich oder Port zu erraten.

• comfy_instance_doctor - Ermittelt die verbundene PID, den Besitzer/Supervisor, den Port, die Code-/Daten-/Benutzer-/Eingabe-/Ausgabe-/Modell-Stammverzeichnisse, die Desktop-Installation, Versionen und Sicherheitswarnungen.

• comfy_list_artifacts - Bestandsaufnahme von Bild-, Video-, Audio-, Mesh- und anderen Ausgaben, mit einem lokalen Ausgabeverzeichnis-Fallback nach Zurücksetzungen des Verlaufs.

• comfy_get_artifact - Sichere Metadaten für ein Ausgabeartefakt auflösen, ohne Pfad-Traversal zu erlauben.

• comfy_get_environment_status - Konfigurierte/zwischengespeicherte comfy-env-Umgebungen und Laufzeitgesundheit überprüfen.

• comfy_list_workers - Aktive isolierte Worker, PIDs, Umgebungen und Gesundheit auflisten.

MCP-Ressourcen

Sechs feste Ressourcen:

• comfy://system/info - Systemstatistiken, GPU-Informationen, ComfyUI-Version

• comfy://server/capabilities - Erkanntes Serverprofil, Version, Frontend-Version, Authentifizierungsmethode, WebSocket-Verfügbarkeit, OpenAPI-Version, Cache-Anbieter

• comfy://nodes/catalog - Knotenkatalog-Vorschau (erste 100 Namen)

• comfy://models/{folder} - Modellauflistung nach Ordner (checkpoints, loras, vae, diffusion_models, text_encoders, usw.)

• comfy://embeddings - Verfügbare Embeddings

• comfy://api/openapi - Optionale OpenAPI 3.1-Aufnahme, wenn die verbundene Bereitstellung /openapi.json bereitstellt; gibt andernfalls {"error": ...} zurück.

Plus vier Ressourcenvorlagen (parametrisierte URIs):

• comfy://nodes/catalog/{page} - Seitierter Knotenkatalog, 100 Knoten pro Seite ({page} = 0, 1, 2, ...)

• comfy://nodes/by-category/{category} - Knoten class_types, deren Kategorie mit dem angegebenen Präfix beginnt (z.B. sampling, loaders/video)

• comfy://templates/catalog - Workflow-Vorlagen, die von ComfyUI-Kern + benutzerdefinierten Knoten angeboten werden (über /workflow_templates)

• comfy://docs/{node_class} - Lokalisiertes eingebettetes Markdown aus /docs/<class>/en.md, mit strukturierten Fork- und Objektinfo-Fallbacks.

So wird es verwendet (Praktischer Workflow)

1. MCP-Client mit ComfyPilot verbinden.

2. Systemzustand und VRAM-Reserven überprüfen.

3. Einen Workflow erstellen (Vorlage oder benutzerdefiniertes API-JSON).

4. Validieren, dann den Prompt in die Warteschlange stellen.

5. Fortschritt bis zum Abschluss verfolgen.

6. Das Ausgabebild abrufen (inline im Chat angezeigt).

7. Bei Bedarf an Festplatte/TD/Blender weiterleiten. Snapshot bei stabilen Meilensteinen.

Wofür es gut geeignet ist

• Erstellen und Iterieren von ComfyUI-Workflows durch Konversation.

• Familienbewusste Generierung über 11 Modellfamilien (SD 1.5, SDXL, SD 3.5, Flux 2, Qwen-Image, Wan 2.2, LTX-2, HunyuanVideo, Hunyuan3D, ACE-Step, Ernie Image) für Bilder, Videos, 3D-Meshes und Musik. Plus 5 familienunabhängige Absichten (Super-Resolution via SUPIR, Frame-Interpolation via RIFE/FILM, Segmentierung via SAM 3.1, natives LoRA-Training, Text-zu-Audio via Stable Audio).

• Ausgehend von gebündelten Blaupausen für jede Familie (13 im Repository enthalten) und anschließender Anpassung.

• 6-stufige Workflow-Validierung (Schema + Katalog + Graph + Anti-Zyklus + Umgebung + Ausführungsrisiko), die defekte Links, Zyklen, fehlende Modelle, veraltete Modelle und überdimensionierte Latents erkennt, bevor Sie ComfyUI erreichen.

• Überwachung der GPU-Ressourcen und Verhinderung von OOM-Situationen via VRAMGuard.

• Zurückgeben generierter Bilder direkt im Chat (Bildinhaltsblöcke).

• App-übergreifende Ausgabe-Weiterleitung an TouchDesigner und Blender mit atomaren Schreibvorgängen + Sidecar-Manifesten (prompt_id, seeds, model refs, dimensions).

• Snapshot/Wiederherstellung für zerstörungsfreie Workflow-Experimente, jetzt optional dauerhaft über Neustarts hinweg.

• Lernen und Wiedergeben wiederverwendbarer Workflow-Muster über die Technikbibliothek.

• Parameter-Sweeps (N Variationen eines einzelnen Widget-Werts in die Warteschlange stellen).

• Importieren eines Workflows aus den eingebetteten Metadaten eines gespeicherten PNGs.

• Rendern jedes Workflows als Mermaid zur schnellen visuellen Inspektion.

• Direktes Durchsuchen von HuggingFace und CivitAI nach Modellen.

Wofür es nicht gut geeignet ist

• Ersetzen künstlerischer Leitung von allein.

• Streaming von Echtzeit-Videoausgabe (Snapshots und Abfragen, keine Live-Frames).

• "Einmalige perfekte Generierung" ohne iterative Verfeinerung.

• Laufen ohne eine funktionierende ComfyUI-Instanz irgendwo (Cloud oder lokal). Die Lebenszyklus-Tools (comfy_launch_server, comfy_install_node, comfy_install_workflow_deps, comfy_download_model) können eine lokale Installation von Null auf bereit bringen, benötigen aber comfy-cli im PATH — installieren Sie es zuerst via pipx install comfy-cli oder uvx --from comfy-cli comfy ....

Modellfamilien

11 erstklassige Modellfamilien plus 5 familienunabhängige Absichtsüberschreibungen. Jede Familie hat eine Builder-Vorlage (oder mehrere), die einen Workflow ausgibt, der der richtigen Graphtopologie entspricht. Die Familie wird aus dem Checkpoint-Dateinamen erkannt; Sie können dies überschreiben, indem Sie checkpoint= in den Parametern übergeben. Absichtsüberschreibungen überspringen die Familienerkennung vollständig und werden nach Absichtsnamen verteilt.

Absichtsüberschreibungen (familienunabhängig; nach Absichtsnamen verteilt, unabhängig von der erkannten Checkpoint-Familie):

Transporte

• stdio (Standard) - Am besten für lokale Clients wie Claude Code, Claude Desktop, Cursor.

• streamable-http - Am besten für gehostete / entfernte Bereitstellungen. Aktivieren mit:

uv run comfypilot --transport streamable-http --host 0.0.0.0 --port 8765

Support-Matrix

Schnelleinrichtung

Option 1: MCPB (Ein-Klick, Claude Desktop)

Am einfachsten für Claude Desktop-Benutzer:

1. Laden Sie comfypilot-v1.9.0.mcpb von der neuesten Version herunter.

2. Doppelklicken Sie auf die Datei (oder ziehen Sie sie in Claude Desktop > Einstellungen > Erweiterungen).

3. Claude Desktop zeigt ein Formular für COMFY_URL, COMFY_API_KEY und die anderen Konfigurationsfelder an — füllen Sie aus, was Sie benötigen.

4. Klicken Sie auf Installieren. Der Neustart erfolgt automatisch.

MCPB verwendet den Server-Modus type: "uv", sodass Python-Abhängigkeiten (mcp, httpx, pydantic, websockets) von uv beim ersten Start aufgelöst werden. Sie benötigen uv auf dem Host installiert — uv installieren.

Das Bundle enthält manifest.json + pyproject.toml + das vollständige Paket src/comfy_mcp/ + die 13 gebündelten Blueprints. Manifest: manifest.json.

Option 2: Lokale Entwicklungslaufzeit

git clone https://github.com/dreamrec/ComfyPilot.git
cd ComfyPilot
uv sync
uv run comfypilot

Option 3: Claude Code-Plugin

claude plugin add /path/to/ComfyPilot

Option 4: Codex

Installieren Sie das Checkout und registrieren Sie seinen stdio-Server:

uv sync
codex mcp add comfypilot --env COMFY_URL=http://127.0.0.1:8188 -- uv run --directory /path/to/ComfyPilot comfypilot

Codex speichert die MCP-Konfiguration in ~/.codex/config.toml; die CLI, die IDE-Erweiterung und die Desktop-App teilen sich diese Konfiguration. Starten Sie Codex nach dem Ändern von MCP-Servern neu.

Lokale Überschreibung

Wenn Ihre ComfyUI-Instanz nicht unter 127.0.0.1:8188 läuft (Tailscale, Remote-LAN, benutzerdefinierter Port), kopieren Sie .mcp.local.json.example in .mcp.local.json und bearbeiten Sie es. Die Datei .mcp.local.json wird von git ignoriert, sodass pro Maschine unterschiedliche URLs und Geheimnisse nie committet werden.

MCP-Bundle (Standardisiert)

ComfyPilot enthält ein standardmäßiges MCP-Bundle im Repository:

• mcp/manifest.json

• mcp/profiles/claude-desktop.json, cursor.json, generic.json

Die gebündelten Profil-JSONs verwenden uv run mit --directory; ersetzen Sie /path/to/ComfyPilot durch Ihren Checkout-Pfad, wenn Sie sie in eine Client-Konfiguration kopieren. Wenn Sie aus diesem Repository heraus starten, verwendet .mcp.json bereits ${CLAUDE_PLUGIN_ROOT}.

Manuelles Client-Konfigurationsbeispiel (Claude Desktop):

{
  "mcpServers": {
    "comfypilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ComfyPilot", "comfypilot"],
      "env": {
        "COMFY_URL": "http://127.0.0.1:8188",
        "COMFY_API_KEY": ""
      }
    }
  }
}

Umgebungsvariablen

Testsuite

Führen Sie die Testsuite aus:

uv run pytest -v

Führen Sie eine bestimmte Kategorie aus:

uv run pytest tests/test_builder.py -v

Für einen schnellen Smoke-Test:

uv run pytest -q

Zuverlässigkeitsgewohnheit

Behandeln Sie dies als obligatorisch für jede sinnvolle Aufgabe: vor Generierungen VRAM prüfen, vor Workflow-Änderungen Snapshot erstellen, nach Builds validieren, nach Fehlern comfy_detect_instability prüfen.

Lizenz

MIT

dreamrec // ComfyPilot // live laugh diffuse