GPT Image Playground MCP

Lass deinen Agenten GPT Image Playground über den Browser nutzen.

Keine Änderungen am Playground-Quellcode nötig. Nach der Installation der Browsererweiterung und einer einmaligen Verbindungseinrichtung kann der Agent Bildgenerierungsaufgaben einreichen, den Aufgabenfortschritt verfolgen und die erzeugten Originalbilder lokal speichern.

Dieses Projekt stellt die Seitenbasis des Playgrounds über CookSleep/gpt_image_playground bereit. Dieses Projekt bietet eine MCP-Brücke für die auf der Seite sichtbaren Aktionen und enthält den Playground-Quellcode weder, noch verändert es ihn.

[!NOTE] Der Playground ist weiterhin für den Aufruf der Bild-API und die Verwaltung seines eigenen Anmeldestatus verantwortlich. Dieses Tool überträgt nur Aufgaben und bedient die Seite.

Das kannst du damit tun

• den Agenten anhand einer Beschreibung ein Bild erzeugen lassen;

• abfragen, ob eine Aufgabe bereits abgeschlossen ist;

• für eine bestimmte Aufgabe das Originalbild herunterladen;

• mehreren Agenten die Nutzung derselben Browser-Aufgabenwarteschlange erlauben;

• mit lokalen Referenzbildern an der Generierung teilnehmen.

Die zugehörigen MCP-Tools sind generate_image, get_task_status und download_image.

Related MCP server: openai-gpt-image-1-mcp

So funktioniert es

Agent
  -> MCP stdio
  -> 本机桥接服务
  -> Chromium 扩展
  -> Playground 页面
  -> 生成并返回图片

Aufgaben werden vom lokalen Bridge-Dienst in der Reihenfolge ihrer Einreichung nacheinander verarbeitet. Für die Bildgenerierung gibt es keine feste 20-Sekunden-Frist; nach der Übernahme einer Aufgabe während der Erweiterung von Warten darauf, bis die Seite fertig ist, und bleibt verbunden. Verschiedene Bilder können unterschiedlich lange für die Generierung brauchen, was nicht zu doppelter Einreichung oder automatischer Neuordnung der Aufgaben führt.

Nach dem Schließen des Browsers können Seitenaufgaben nicht weiter ausgeführt werden. Öffne den Browser erneut und prüfe zuerst den Status der ursprünglichen Aufgaben, bevor du neue Aufgaben einreichst.

Bevor du beginnst

Halte Folgendes bereit:

• Node.js 18 oder höher;

• Chrome, Chromium oder einen anderen Chromium-Browser mit Manifest-V3-Unterstützung;

• eine Browserseite, auf der GPT Image Playground normal geöffnet wird;

• einen MCP-fähigen Agent-Client.

Schnellstart

1. Projekt abrufen und bauen

Hole das Projekt von GitHub:

git clone https://github.com/PEKI7483/image-playground-mcp.git
cd image-playground-mcp
npm install
npm run build

Wenn du das Projekt in ein anderes Verzeichnis legst, ist <Projektstammverzeichnis> weiter unten das geklonte Verzeichnis image-playground-mcp.

Nach dem Bau sollte dist/ die Dateien server.js, bridge.js und bridgeMain.js enthalten.

2. Verbindungscode generieren

Der Verbindungscode schützt den lokalen Bridge-Dienst und ist kein Playground-API-Key. Erzeuge einen zufälligen Verbindungscode und bewahre ihn sicher auf:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Die Erweiterung und jeder Agent-Client müssen denselben Verbindungscode verwenden. Committe den Verbindungscode nicht in das Repository und veröffentliche ihn nicht in Logs.

Die Standard-Bridge-Adresse ist http://127.0.0.1:8787. Falls der Port belegt ist, kannst du einen anderen Port verwenden, zum Beispiel 8790 – aber die Erweiterung und alle Agents müssen übereinstimmen.

3. Browsererweiterung installieren

1. Öffne Chrome oder Chromium und rufe chrome://extensions auf.

2. Aktiviere oben rechts den „Entwicklermodus“.

3. Klicke auf „Entpackte Erweiterung laden“.

4. Wähle:

   <项目根目录>/extension

5. Klicke in der Browser-Symbolleiste auf das Symbol der Erweiterung, um das Erweiterungsfenster zu öffnen.

6. Klicke oben auf „Verbindungseinstellungen“.

7. Setze bei „Bildtool-Adresse“ den Wert http://127.0.0.1:8787 und bei „Verbindungscode“ den eben erzeugten Verbindungscode.

8. Klicke auf „Speichern und prüfen“. Nach erfolgreicher Verbindung kehrt das Fenster zur „Betriebsübersicht“ zurück.

Die Einrichtung erfolgt ausschließlich im kleinen Erweiterungsfenster und öffnet keinen neuen Tab. Die Erweiterung speichert Bridge-Adresse und Verbindungscode, aber keinen Playground-API-Key.

4. Agent auswählen

Schließe zuerst die Erweiterungskonfiguration ab und wähle danach die zu deinem Agent-Client passende Methode. Alle Agents können sich denselben Bridge-Dienst teilen, müssen aber denselben Verbindungscode und Port verwenden.

Codex CLI und Codex-App

Codex CLI, Codex-App und die IDE-Erweiterung teilen sich die MCP-Konfiguration. Setze <Projektstammverzeichnis> und den Verbindungscode auf die tatsächlich verwendeten tatsächlichen Werte und führe Folgendes aus:

codex mcp add gpt-image-playground \
  --env MCP_BRIDGE_TOKEN=替换为连接码 \
  --env MCP_BRIDGE_PORT=8787 \
  -- node "<项目根目录>/dist/server.js"

Konfiguration prüfen:

codex mcp list

Weitere Optionen findest du in der offiziellen Codex-MCP-Dokumentation.

Claude Code

claude mcp add --transport stdio gpt-image-playground \
  --env MCP_BRIDGE_TOKEN=替换为连接码 \
  --env MCP_BRIDGE_PORT=8787 \
  -- node "<项目根目录>/dist/server.js"

Gemini CLI

Gemini CLI konfiguriert lokale Dienste in der Regel über die MCP-Konfigurationsdatei. Füge in der Datei settings.json unter mcpServers Folgendes hinzu:

{
  "gpt-image-playground": {
    "command": "node",
    "args": ["<项目根目录>/dist/server.js"],
    "env": {
      "MCP_BRIDGE_TOKEN": "替换为连接码",
      "MCP_BRIDGE_PORT": "8787"
    }
  }
}

Cursor, Cline, Roo Code, Windsurf und Claude Desktop

Diese Clients können den lokalen STDIO-Dienst auf der MCP-Einstellungsseite hinzufügen oder die entsprechende JSON-Konfiguration bearbeiten. Führe das folgende Objekt gpt-image-playground in ein vorhandenes mcpServers-Objekt ein und behalte dabei die anderen Serverkonfigurationen bei:

{
  "gpt-image-playground": {
    "command": "node",
    "args": ["<项目根目录>/dist/server.js"],
    "env": {
      "MCP_BRIDGE_TOKEN": "替换为连接码",
      "MCP_BRIDGE_PORT": "8787"
    }
  }
}

Häufige Orte sind:

• Cursor: .cursor/mcp.json im Projektverzeichnis oder Cursor Settings > MCP;

• Cline: die Seite MCP Servers in der Erweiterung;

• Roo Code: die Seite MCP Servers in der Erweiterung;

• Windsurf: die MCP-Einstellungsseite oder die MCP-Konfigurationsdatei;

• Claude Desktop: mcpServers in claude_desktop_config.json.

Nach dem Speichern bitte den Client neu starten oder die MCP-Konfiguration neu laden.

Wenn der MCP-Client dist/server.js startet, wird das MCP-Protokoll über stdio bereitgestellt und gleichzeitig der lokale Bridge-Dienst gestartet. Ein manueller Aufruf von npm start ist normalerweise nicht erforderlich.

Starten und Verbindung bestätigen

1. Öffne GPT Image Playground und lasse die normale Seite im Galerie-Modus geöffnet.

2. Stellen Sie sicher, dass das Eingabefeld für die Aufforderung und das Bild-Upload-Steuerungsfeld auf der Seite sichtbar sind.

3. Starte oder starte deinen Agent-Client neu, damit er die zuvor hinzugefügten MCP-Konfiguration laden.

4. Klicke in der Browser-Symbolleiste auf das Symbol der Erweiterung.

5. Prüfe in der „Betriebsübersicht“, ob Bridge-Dienst, Erweiterungsverbindung und Playground-Seite einen normalen Status haben.

Du kannst die Verbindung auch über den Health-Check-Endpunkt prüfen:

curl -H 'X-MCP-Bridge-Token: 替换为连接码' \
  http://127.0.0.1:8787/v1/health

Beispiel für den Zustand (Health Status):

{
  "bridge": "running",
  "extensionConnected": true,
  "playgroundTabCount": 1,
  "queueLength": 0
}

Beispiele für Aufrufe

Ein Bild erzeugen

Rufe generate_image mit mindestens einer Aufforderung auf:

{
  "prompt": "一只戴红色围巾的橘猫，工作室摄影风格"
}

Das Tool warten darauf, dass die Seite fertig wird, und verwendet keine 20-Sekunden-Frist als Frist. Mehrere Agents können sich gleichzeitig über denselben Bridge-Adresse verbinden; Die Aufgaben landen in derselben FIFO-Warteschlange und werden nacheinander ausgeführt.

Referenzbilder verwenden

Referenzbilder können direkt über die MCP-Parameter übergeben werden; du musst das Upload-Steuerelement im Playground nicht manuell anklicken:

{
  "prompt": "保留参考图的构图，改成水彩插画",
  "reference_image_paths": [
    "/absolute/path/reference.png",
    "/absolute/path/style.jpg"
  ]
}

Unterstützt werden PNG, JPEG/JPG, WebP, GIF und AVIF; höchstens 16 Bilder, wobei ein einzelnes Bild nicht über 8 MiB und die Gesamtgröße nicht über 24 MiB liegt. Nachdem der MCP-Dienst die lokalen Dateien gespeichert hat, fügt die Erweiterung die Bedingungen in das vorhandene Multi-File-Upload-Steuerelement des Playgrounds an; die Bildverarbeitung übernimmt weiterhin die Playground-Seite.

Erzeugtes Ergebnis herunterladen

Nach erfolgreichem generate_image wird mit der zurückgegebenen task_id download_image aufrufen:

{
  "task_id": "上一步返回的 task_id",
  "output_path": "/absolute/path/generated.png",
  "image_index": 0
}

output_path muss ein absolut Pfad sein. Wenn eine Datei bereits vorhanden ist, ist der Erfolg idempotent nur dann korrekt, wenn der Inhalt exakt übereinstimmt; andernfalls das Tool weist auf einen Konflikt hin und überschreibt die vorhandene Datei nicht.

Das Originalbild im Detail-Dialog wird möglicherweise erst später geladen als die Miniaturansicht der Aufgabenkarte. Die Erweiterung kompatibel mit normalen img-Bildern, wartet maximal 60 Sekunden und schließt den Detail-Dialog, nachdem der Download abgeschlossen oder fehlgeschlagen ist.

Sicherheit und Datenschutz

[!IMPORTANT] Dein Anmeldestatus und dein API-Key für Playground werden weiterhin von Playground selbst verwaltet. Dieses Tool hat nur auf die Seite zu und liest oder speichert keine Cookies, localStorage, IndexedDB, JavaScript-Variablen der Seite oder Schlüssel aus API-Antworten.

• Der Verbindungscode dient nur zum Schutz der lokalen Bridge-Schnittstelle und ist kein Playground-API-Key;

• Der Bridge-Dienst läuft standardmäßig nur auf der lokalen Loopback-Adresse;

• Die Bildgenerierung erfolgt über die sichtbare Playground-Seite, nicht durch direkte Aufrufe der Bild-API;

• Referenzbilder werden von MCP-Dienst des Dienstes gelesen und der Playground-Seite zur Verarbeitung übergeben;

• Mehrere Agents können sich den Dienst teilen, sollten aber denselben Verbindungscode und port verwenden.

Häufig gestellte Fragen

Die Erweiterung zeigt „Dienst nicht erreichbar“

Bitte prüfe in der folgenden Reihenfolge:

1. Wurde dist/server.js vom Agent-Clients bereits gestartet und geladen?

2. Ist die Bridge-Adresse in der Erweiterung http://127.0.0.1:8787?

3. Stimmt der Verbindungscode in der Erweiterung exakt mit struktur in der Agent-Konfiguration überein?

4. Hast du nach Änderungen am Erweiterungscode bei chrome://extensions auf „Neu laden“ geklickt?

5. Hast du die normale Gallery-Seite von GPT Image Playground geöffnet?

Falls weiterhin keine Verbindung zustande kommt, verwende den Health-Check-Befehl oben und bewahre das Ergebnis auf, um es weiter zu lokalisieren.

Die Anzahl der Playground-Seiten ist 0

Öffne die Seite im normalen Gallery-Modus von GPT Image Playground und stelle sicher, dass das Eingabefeld für den Prompt sichtbar ist. Die Erweiterung funktioniert auf. Sie funktioniert nicht über direkte Aufrufe der Bild-API und bearbeite keine Seiten ohne entsprechende Seitenelement.

Die Generierung dauert lange, der Agent scheint nicht zu reagieren

Die Generierungszeit hängt von Prompt, Referenzbildern und Seitenstatus ab. Prüfe zuerst die Aufgabenkarten im Playground und die Betriebsübersicht der Erweiterung; klicke nicht erneut auf „Generieren“. Eine bereits übernommene Aufgabe wird weiterhin auf die Fertigstellung der Seite warten; bei Bedarf kannst du mit get_task_status nachfragen.

Referenzbilder erscheinen nicht

Bitte bestätige:

• Der Dateipfad ist absolut;

• das Datei format wird unterstützt;

• das einzelne Bild nicht über 8 MiB liegt und die Gesamtgröße 24 MiB nicht übersteigt;

• die Anzahl der Bilder nicht mehr als 16 beträgt;

• das Multi-File-Upload-Steuerelement auf der Playground-Seite vorhanden ist.

Download des Originalbilds schlägt fehl

Prüfe zuerst, ob die Aufgabe abgeschlossen ist, die Aufgabenkarte noch sichtbar ist und verwende einen neuen absoluten Ausgabepfad. Der Download liest das Originalbild aus dem Detail-Dialog und nicht über den Browser-Speicher.

Konfiguration

Wenn du den Bridge-Dienst zur Fehlerbehandlung separat starten möchtest, verwende:

MCP_BRIDGE_TOKEN='替换为连接码' MCP_BRIDGE_PORT=8787 npm run bridge

Normalerweise ist es nicht nötig, diesen Befehl manuell über den Befehl cmd auszuführen. Wenn der MCP-Client dist/server.js startet, wird gleichzeitig der lokale Bridge-Dienst gestartet.

Feedback und Hilfe

Wenn du auf ein Problem stößt, reiche gerne ein Issue ein. Um uns zu helfen, die Situation, bitte stell die folgenden Informationen bereit:

• den verwendeten Agent-Client und dessen Version;

• Browser und Version;

• den Status aus der Betriebsübersicht der Erweiterung;

• das Ergebnis des Health-Check-Endpunkts;

• die Fehlermeldungen der zugehörigen Aufgaben.

Entferne vor dem Teilen von Logs den Verbindungscode, persönliche Pfade und andere sensible Informationen.

Design-Grenzen

• Dieses Projekt ändert den Quellcode von GPT Image Playground nicht;

• Der API-Key verbleibt in der Browser-Sitzung des Playground selbst; MCP und Erweiterung lesen ihn nicht;

• Aufgaben werden nur über die lokale Loopback-Adresse bereitgestellt und erfordern einen Verbindungscode;

• Nach dem Schließen des Browsers können Seitenaufgaben nicht weiter ausgeführt werden;

• Aufgaben werden seriell verarbeitet, damit nicht mehrere Agents gleichzeitig dieselbe Playground-Seite bedienen.

Danke, dass du dir die Zeit genommen hast, dieses Tool auszuprobieren. Ich hoffe, es macht die Bildgenerierung flüssiger und macht die Zusammenarbeit zwischen Agent und Playground natürlicher.