Schritt für Schritt: MCP-Server für Bildgenerierung einrichten
Schritt 1: API-Schlüssel besorgen und sicher aufbewahren
Besorgen Sie sich über die Freebeat-Website einen Freebeat-API-Schlüssel. Bewahren Sie ihn während der Vorbereitung der Clientkonfiguration an einem sicheren Ort auf. Der Server liest den Schlüssel aus der Umgebungsvariable FREEBEAT_API_KEY.
So erkennen Sie den Erfolg: Sie haben einen gültigen Schlüssel zur Eingabe im MCP-Client bereit, ohne ihn in einer öffentlichen Datei oder Nachricht zu hinterlegen.
Häufiger Fehler, den Sie vermeiden sollten: Den Beispieltext your-api-key-here in der endgültigen Konfiguration unverändert zu lassen.
Schritt 2: Sicherstellen, dass der Client das Paket ausführen kann
Verwenden Sie einen kompatiblen MCP-Client wie Claude Desktop oder Cursor. Stellen Sie sicher, dass Node.js/npm und Netzwerkzugriff in der Umgebung verfügbar sind, in der der Client gestartet wird, da der dokumentierte Befehl das Paket über npx ausführt.
So erkennen Sie den Erfolg: Die Clientumgebung kann den Befehl npx finden und Online-Dienste erreichen.
Häufiger Fehler, den Sie vermeiden sollten: npm in einer anderen Umgebung zu testen als derjenigen, die der Desktop-Client verwendet.
Schritt 3: Serverkonfiguration hinzufügen
Fügen Sie im MCP-Konfigurationsbereich Ihres Clients einen Server mit dem Namen freebeat hinzu. Die dokumentierte Konfigurationsstruktur ist für Claude Desktop und Cursor identisch:
So erkennen Sie den Erfolg: Die Konfiguration ist gültiges JSON und enthält den Befehl, die Argumente und die Umgebungsvariable.
Häufiger Fehler, den Sie vermeiden sollten: Abschließende Kommas einzufügen oder den Paketnamen zu ändern, da dies den Client daran hindern kann, den Server zu starten.
Schritt 4: Umgebungsvariable festlegen
Ersetzen Sie den Platzhalterwert in der lokalen Clientkonfiguration durch Ihren API-Schlüssel. Verwenden Sie exakt den dokumentierten Variablennamen: FREEBEAT_API_KEY.
So erkennen Sie den Erfolg: Der Schlüssel ist in der Serverumgebung hinterlegt und der Servereintrag bleibt gültiges JSON.
Häufiger Fehler, den Sie vermeiden sollten: Einen anderen Variablennamen zu verwenden, Leerzeichen zum Schlüssel hinzuzufügen oder das Geheimnis in gemeinsam genutzten Protokollen offenzulegen.
Schritt 5: Konfiguration speichern und Verbindung erneuern
Speichern Sie die MCP-Einstellungen. Starten Sie den Client neu oder aktualisieren Sie ihn, falls der Servereintrag nicht automatisch neu geladen wird. Prüfen Sie anschließend die verfügbaren MCP-Werkzeuge des Clients auf Freebeat-Funktionen.
So erkennen Sie den Erfolg: Der Client erkennt den Freebeat-Server und stellt dessen verfügbare Werkzeuge bereit.
Häufiger Fehler, den Sie vermeiden sollten: Probleme mit Generierungsaufrufen zu beheben, bevor Sie sich vergewissert haben, dass der Server verbunden ist und seine Werkzeuge angezeigt werden.
Schritt 6: Bildmodell ermitteln und Hinweise dazu prüfen
Rufen Sie list_models mit type: "image" auf. Wählen Sie ein zurückgegebenes Modell aus und rufen Sie bei Bedarf get_model_help mit dessen numerischer model_id oder API-Modellkennung auf, um Beispiele und Einschränkungen einzusehen. Dieser Schritt zur Ermittlung von Bildmodellen erspart Ihnen das Raten von Modellkennungen.
So erkennen Sie den Erfolg: Sie haben ein gültiges Bildmodell ausgewählt und kennen alle für Ihre Anfrage relevanten modellspezifischen Anforderungen.
Häufiger Fehler, den Sie vermeiden sollten: Einen angenommenen Modellnamen fest zu codieren, statt ein Modell aus der aktuellen Antwort auszuwählen.
Schritt 7: Bild generieren und Batch-Status abfragen
Rufen Sie generate_image mit dem ausgewählten Modell und einem aussagekräftigen Prompt auf. Der Prompt muss nach dem Entfernen überflüssiger Leerzeichen 1–2.000 Zeichen umfassen. Optionale Felder sind size, resolution, quality und count; für count gilt standardmäßig 1. Bei GPT-Image 2 (Modell-ID 108) werden für nicht angegebene Werte standardmäßig medium für die Qualität und 1024x1024 für die Auflösung verwendet. Wird keine Auflösung angegeben, aber eine Größe festgelegt, übermittelt der Server aus Kompatibilitätsgründen auch die Größe als Auflösung.
So erkennen Sie den Erfolg: Die Anfrage gibt eine Batch-ID zurück, mit der Sie den Aufgabenstatus prüfen und nach Abschluss die Bild-URLs abrufen können.
Häufiger Fehler, den Sie vermeiden sollten: Einen leeren, zu langen oder nur aus Leerzeichen bestehenden Prompt zu senden. Beachten Sie die Prompt-Einschränkungen und prüfen Sie die Modellhinweise, bevor Sie es erneut versuchen.
Schritt 8: Status prüfen und Ergebnis ansehen
Fragen Sie get_task_status ab und übergeben Sie die zurückgegebene batch_id als task_id. Bei einem Open-RPC-Bildbatch können Sie zusätzlich serial_no übergeben, um ein einzelnes Element zu prüfen. Achten Sie auf einen Endstatus wie completed oder failed. Abgeschlossene Bild-Batches enthalten Bild-URLs in der Statusantwort, mit Feldern wie image_url oder edit_images.
So erkennen Sie den Erfolg: Die Aufgabe erreicht einen Endstatus und die Antwort enthält bei erfolgreichem Abschluss ein Bildergebnis.
Häufiger Fehler, den Sie vermeiden sollten: get_task_result für einen Open-RPC-Bildbatch aufzurufen. Die abgeschlossenen Bildergebnisse werden direkt von get_task_status zurückgegeben.