gpt-image-mcp

Verleihe Claude Code die Superkraft der Bildgenerierung. Sag „zeichne mir ein Bild“, und Claude Code generiert es direkt in deiner Konversation mit OpenAI gpt-image-2 — ohne die App zu wechseln oder Prompts zu kopieren.

🎯 Was ist das?

Für Claude-Code-Nutzer: Dieses Projekt integriert die gpt-image-2-Bildgenerierung direkt in Claude Code als MCP-Server. Einmal installieren, einmal registrieren, und Claude Code erhält eine native generate_image-Fähigkeit — du beschreibst das Bild in einfacher Sprache (in jeder Sprache), und Claude Code erstellt den Prompt, ruft gpt-image-2 auf und liefert dir ein lokales PNG. Wenn du dir je gewünscht hast, dass Claude es „einfach zeichnet“, statt es zu erklären, ist dies das fehlende Puzzleteil.

Es funktioniert auch als eigenständige CLI und mit jedem anderen MCP-Host — derselbe Kern, überall.

Kein ChatGPT-Plus-Abonnement nötig — nur ein API-Schlüssel, der gpt-image-2 unterstützt.

Ablauf:

You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓

Related MCP server: gpt-image-mcp

✨ Funktionen

• Native Claude-Code-Integration. Einmal registrieren, und Claude Code erhält ein echtes generate_image-Werkzeug — beschreibe jede Szene in einfacher Sprache und erhalte ein lokales PNG direkt im Chat.

• Zwei Einstiegspunkte, ein Kern. Dieselbe Generierungslogik betreibt sowohl einen MCP-Server als auch eine einfache CLI.

  • gpt-image-mcp --mcp → Stdio-MCP-Server mit generate_image- / list_images-Werkzeugen

  • gpt-image-mcp "a cat in a spacesuit" → einmalige CLI-Generierung

• Beliebiges OpenAI-kompatibles Backend. Setze OPENAI_BASE_URL auf einen beliebigen Ort (Wiederverkäufer, Proxys, selbst gehostete Gateways).

• Qualitätsstufen entsprechen dem eigenen low / medium / high-Regler von gpt-image-2. Keine zusätzlichen Modelle, keine Kostenüberraschungen.

• Schlüssel nie im Code. Alles läuft über Umgebungsvariablen — Geheimnisse bleiben außerhalb deines Repos.

• Async-sicher. Bilder werden als base64-dekodierte PNGs lokal auf die Festplatte gestreamt; die API schreibt nie selbst auf deine Festplatte.

🧰 Voraussetzungen

• Python 3.10+

• Ein OpenAI-API-Schlüssel oder ein OpenAI-kompatibler Endpunkt (Wiederverkäufer / Gateway / selbst gehostet), der gpt-image-2 bereitstellt (oder ein kompatibles Modell, das du über GPT_IMAGE_MODEL festlegst).

• Python installierbar über pip oder uv.

📦 Installation

Von PyPI

pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv

Aus dem Quellcode

git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

⚙️ Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Tipp: Die Standard-Basis-URL ist der offizielle OpenAI-Endpunkt. Um einen Wiederverkäufer oder Proxy zu nutzen, setze OPENAI_BASE_URL einfach auf dessen /v1-Wurzel — sonst ändert sich nichts.

🚀 Verwendung

Als MCP-Server (Claude Code)

Registriere den Server (ersetze ~/.venv durch deinen tatsächlichen Env-Pfad):

claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp

Starte Claude Code neu, und zwei Werkzeuge sind verfügbar:

• generate_image — generiert ein Bild und speichert es lokal.

  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘

  Parameter: prompt (erforderlich), size, quality, out_name.

• list_images — listet zuvor generierte PNGs auf (neueste zuerst).

Was du in Claude Code sagen kannst:

„Zeichne eine Cyberpunk-Orange-Tabby in einem Raumanzug, Sternenfeld, cineastisch, hohe Qualität.“ → löst generate_image aus

„Generiere einen 1536x1024-Hero-Shot im Querformat: Cyberpunk-Stadt im Regen, Neon- Reflexionen.“ → setzt size + quality

„Welche Bilder habe ich zuvor generiert?“ → löst list_images aus

Keine magische Syntax nötig — beschreibe das Bild einfach in deinen eigenen Worten, in jeder Sprache. Claude Code erledigt den Rest.

Als CLI

export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png

Ohne --no-interactive kannst du in der CLI bei vorhandenem TTY Größe/Qualität interaktiv auswählen.

🖼️ Parameter

size — Leinwandausrichtung:

quality — der eigene Qualitätsregler von gpt-image-2 (einzelnes Modell; Abwägung zwischen Geschwindigkeit/Kosten und Detailtreue):

🛠️ Entwicklung

pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel

Aufbau:

src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints

🔐 Sicherheit

• Dein API-Schlüssel ist niemals in dieses Paket eingebettet. Er wird bei jedem Aufruf aus OPENAI_API_KEY gelesen.

• Über die einzelne Bildgenerierungsanfrage hinaus wird nichts protokolliert oder übertragen.

• Die Verzeichnisse .env und out/ werden standardmäßig von Git ignoriert.

📝 Hinweise und Einschränkungen

• Jede Anfrage dauert in der Regel ~10–60 s, je nach Endpunkt und Qualitätsstufe.

• Dieses Projekt ist nicht mit OpenAI verbunden; es ist ein unabhängiger MCP-Wrapper.

• gpt-image-2 liefert Bilder standardmäßig als Base64 zurück, das dieses Tool dekodiert und lokal auf die Festplatte schreibt. Ein url-Fallback wird ebenfalls unterstützt.

📄 Lizenz

MIT © Garfield-Wuu.

⭐ Unterstützung

Wenn dir das eine lange Suche erspart hat, freuen wir uns über einen Stern. Issues und PRs sind willkommen.

🌐 Andere Sprachen / 其他语言

• 中文版 README (README.zh-CN.md) — 简体中文