image-gen-mcp

Ein MCP-Server, der mit Googles nativen Gemini-Bildmodellen („Nano Banana“) Bilder erzeugt und über Streamable HTTP ausliefert.

Ein Tool, generate_image. Kein Zustand irgendwo und keine eigene Authentifizierung — in Produktion läuft er als Backend hinter mcp-oauth-proxy, bereitgestellt durch cloudrun-mcp-deployment.

DESIGN.md erklärt, warum er so gebaut ist; diese Datei erklärt, wie man ihn ausführt.

Schnellstart (lokal, Token-Auth)

uv sync
export GEMINI_API_KEY="…"                       # from Google AI Studio
export IMAGE_MCP_TOKEN="$(openssl rand -base64 32)"
uv run python -m image_gen_mcp

Richten Sie einen Client auf http://127.0.0.1:8080/mcp mit Authorization: Bearer $IMAGE_MCP_TOKEN aus. Für Claude Code:

claude mcp add --transport http image-gen http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $IMAGE_MCP_TOKEN"

Related MCP server: Imagen MCP Server

Das Tool

generate_image(prompt, aspect_ratio="1:1", image_size="1K", model=None)

Bilder bis einschließlich IMAGE_MCP_INLINE_MAX_BYTES (Standard 1,5 MB) kommen inline zurück und werden im Chat gerendert. Größere Bilder werden in Cloud Storage hochgeladen und als signierte URL zurückgegeben. Die strukturierte Ausgabe meldet immer die tatsächlichen Pixelmaße, das verwendete Modell und die gewählte Zustellungsroute.

Modell- / Auflösungsunterstützung

Nicht unterstützte Kombinationen werden an der Tool-Grenze in Millisekunden abgelehnt, mit einer Meldung, die angibt, was unterstützt ist — statt erst nach einer 30-Sekunden-Roundtrip.

Konfiguration

Alles kommt aus der Umgebung. Siehe .env.example für die kommentierte Liste; das Wesentliche:

Der Server weigert sich zu starten, statt falsch konfiguriert zu laufen: ein fehlender API-Schlüssel und ein völliges Fehlen einer Auth-Grenze (weder statisches Token noch Proxy-Modus) sind beides Startfehler.

Auth

Zwei Varianten, und der Server weigert sich, ohne eine davon zu starten.

Hinter dem Proxy (Produktion). Setzen Sie IMAGE_MCP_TRUST_PROXY_HEADERS=1. Der Proxy authentifiziert den Benutzer bei Google, setzt seine Allowlist durch, entfernt den Authorization-Header des Clients und leitet die Identität als X-Auth-Email / X-Auth-Subject / X-Auth-Scope weiter. Dieser Server wertet diese aus und benötigt keine eigenes Token – eine Anfrage ohne X-Auth-Email erhält eine 401.

Trusting dieser Header ist nur deshalb sicher, weil sonst nichts den Prozess erreichen kann: Im Cloud-Run-Multi-Container-Layout deklariert das Backend keinen Ingress-Port, sodass nur der Proxy in derselben Instanz und der Start-Prober einen Socket zu ihm öffnen können. Aktivieren Sie dies niemals auf einem routierfähigen Port.

ALLOWED_EMAILS ist hier optional und schränkt die Allowlist des Proxys ein – nützlich bei einem Proxy, der eine gesamte Domain zulässt, aber nur wenige Personen sollen für die Bildgenerierung bezahlen. Nicht gesetzt bedeutet „jeder, den der Proxy zugelassen hat“.

Token (lokal, Claude Code). Lassen Sie IMAGE_MCP_TRUST_PROXY_HEADERS ungesetzt und setzen Sie IMAGE_MCP_TOKEN. Aufrufer senden Authorization: Bearer <token>. Die X-Auth-*-Header werden vollständig ignoriert, da sie ohne den Proxy nur nicht vertrauenswürdige Anforderungsdaten sind.

Der Server beendet selbst kein OAuth und hat keine /authorize, /token oder /register-Endpunkte. GOOGLE_OAUTH_CLIENT_ID oder _SECRET zu setzen ist ein Startfehler, kein stilles No-Op – das gehört an den Proxy.

Bild bauen

.github/workflows/build.yml führt Tests aus, erstellt das Image und veröffentlicht es in GitHub Container Registry. Es deployiert nicht – das Deployment übernimmt ein getrenntes Workflow oder ein getrennter Repo.

Veröffentlicht als ghcr.io/ramzpat/image-gen-mcp. Es muss nichts konfiguriert werden: der Workflow authentifiziert sich mit dem eingebauten GITHUB_TOKEN.

Verwendung in einem Deploy-Workflow

Bereitstellen per Digest, nicht per Tag. Ein Pull-through-Cache vor einem veränderlichen Tag wie :latest liefert eifrig ein früheres Image aus; ein Digest kann nicht verallen. Jeder Lauf gibt den Digest in der Job-Zusammenfassung aus, und der Workflow kann aufgerufen werden, wenn man bauen und deployen in einer Pipeline möchte:

jobs:
  build:
    uses: ramzpat/image-gen-mcp/.github/workflows/build.yml@main
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploying ${{ needs.build.outputs.image }}@${{ needs.build.outputs.digest }}"

Aus einem separaten Repository werten Sie den Digest beim Deployment stattdessen auf:

DIGEST=$(docker buildx imagetools inspect \
  ghcr.io/ramzpat/image-gen-mcp:latest --format '{{.Manifest.Digest}}')

Das GHCR-Paket ist standardmäßig privat. Ein Deploy-Job in einem anderen Repository benötigt entweder ein PAT mit read:packages oder definiert das Paket öffentlich in den GitHub-Paketeinstellungen.

Deployment

Deployiert durch cloudrun-mcp-deployment (.github/workflows/deploy-image-gen-mcp.yml), das dieses Image als Backend-Container eines Cloud-Run-Multi-Container-Dienstes ausführt, mit mcp-oauth-proxy davor. Dieses Repo besitzt das GCP-Projekt, die Region, die Allowlist und die Secrets; dieses hier veröffentlicht nur das Image.

Was dieses Deployment für diesen Container setzt:

HOST=0.0.0.0 statt Loopback ist erforderlich, kein Leck: Der Start-Prober von Cloud Run läuft außerhalb des Netzwerk-Namespaces des Containers und kann einen reinen Loopback-Socket nicht erreichen. Nur der Container, der --port deklariert (der Proxy), erhält eingehenden ingress; das Backend bleibt dadurch von außerhalb der Instanz unerreichbar.

Cloud Storage für 2K/4K

gcloud storage buckets create gs://BUCKET --uniform-bucket-level-access
gcloud storage buckets update gs://BUCKET \
  --lifecycle-file=<(echo '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}')

# The runtime service account signs URLs through the IAM Credentials API,
# because it has no private key file. It needs this role *on itself*:
gcloud iam service-accounts add-iam-policy-binding RUNTIME_SA \
  --member="serviceAccount:RUNTIME_SA" --role=roles/iam.serviceAccountTokenCreator
gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member="serviceAccount:RUNTIME_SA" --role=roles/storage.objectAdmin

Die Bindungs serviceAccountTokenCreator-Bindung erst weggelassen werden, ist der häufigste Grund dafür, dass signierte URLs defekt sind.

Tests

uv run pytest -q

57 Tests: Start-Schutzmechanismen, Identitätsermittlung (sowohl Proxy-Header, als auch statisches Token, wobei jede jeweils die Anmeldedaten des anderen ignoriert), Tool- und Validierung, Zustellung und End-to-End-Smoke-Tests, die einen echten MCP-Client über echtes HTTP gegen uvicorn fahren – im Token- und im Proxy-Production-Setup.

Kosten

Jeder aus der Allowlist verpasste Benutzer bezieht sich auf einen einzigen API-Key. Die Steuerelemente, in salender Wirksamkeitsstufen: --max-instances, IMAGE_MCP_MAX_CONCURRENCY, eine GCP-Budgetwarnung für die Abrechnung sowie IMAGE_MCP_RATE_PER_HOUR. Der Limitwert wird pro Instanz gezählt, daher ist die tatsächliche obere Grenze IMAGE_MCP_RATE_PER_HOUR × --max-instances.# image-gen-mcp

Ein MCP-Server, der mit Googles nativen Gemini-Bildmodellen („Nano Banana“) Bilder erzeugt und über Streamable HTTP ausliefert.

Ein einziges Tool, generate_image. Kein Zustand irgendwo und keine eigene Authentifizierung – in Produktion läuft er als Backend hinter mcp-oauth-proxy, bereitgestellt durch cloudrun-mcp-deployment.

DESIGN.md erklärt, warum er so gebaut ist; diese Datei erklärt, wie man ihn ausführt.

Schnellstart (lokal, Token-Auth)

uv sync
export GEMINI_API_KEY="…"                       # from Google AI Studio
export IMAGE_MCP_TOKEN="$(openssl rand -base64 32)"
uv run python -m image_gen_mcp

Richte einen Client auf http://127.0.0.1:8080/mcp mit Authorization: Bearer $IMAGE_MCP_TOKEN aus. Für Claude Code:

claude mcp add --transport http image-gen http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $IMAGE_MCP_TOKEN"

Das Tool

generate_image(prompt, aspect_ratio="1:1", image_size="1K", model=None)

Bilder bis einschließlich IMAGE_MCP_INLINE_MAX_BYTES (Standard: 1,5 MB) kommen inline zurück und werden im Chat gerendert. Größere Bilder werden in Cloud Storage hochgeladen und als signierte URL zurückgegeben. Die strukturierte Ausgabe meldet immer die tatsächlichen Pixelmaße, das verwendete Modell und die verwendete Zustellungsroute.

Modell- / Auflösungsunterstützung

Nicht unterstützte Kombinationen werden an der Tool-Grenze in Millisekunden abgelehnt, mit einer Meldung, die benennt, was unterstützt ist – statt erst nach einem 30-Sekunden-Roundtrip.

Konfiguration

Alles kommt aus der Umgebung. Siehe .env.example für die annotierte Liste; das Wesentliche:

Der Server weigert sich zu starten, statt falsch integriert zu laufen: Fehlender API-Key und überhaupt keine Auth-Grenze (weder statisches Token noch Proxy-Modus) sind beides Startfehler.

Auth

Zwei Formen, und der Server weigert sich, wenn keine davon gilt.

Hinter dem Proxy (Produktion). Setze IMAGE_MCP_TRUST_PROXY_HEADERS=1. Der Proxy authentifiziert den Benutzer gegen Google, erzwingt seine Allowlist, entfernt den Authorization-Header des Clients und reicht die Identität als X-Auth-Email / X-Auth-Subject / X-Auth-Scope weiter. Dieser Server liest diese und benötigt kein eigenes Token – eine Anfrage ohne X-Auth-Email erhält eine 401.

Headers zu vertrauen ist nur deshalb sicher, weil sonst nichts den Prozess erreichen kann: Im Cloud-Run-Multi-Container-Layout erklärt das Backend keinen Ingress-Port, sodass nur der Proxy in derselben Instanz und der Start-Prob einen Socket zu ihm öffnen können. Aktiviere das nie auf einem routierbaren Port.

ALLOWED_EMAILS ist hier optional und verkleinert die Allowlist des Proxy – nützlich, wenn der Proxy eine gesamte Domain erlaubt, aber nur wenigen Personen Bildgenerierung Geld kosten soll. Nicht gesetzt bedeutet „alle, die der Proxy zugelassen hat“.

Token (lokal, Claude Code). Lass IMAGE_MCP_TRUST_PROXY_HEADERS ungesetzt und setze IMAGE_MCP_TOKEN. Aufrufer senden Authorization: Bearer <token>; die X-Auth-*-Header werden vollständig ignoriert, da sie ohne den Proxy nur nicht vertrauenswürdige Request-Daten sind.

Der Server beendet kein OAuth und hat keine /authorize-, /token- oder /register-Endpunkte. GOOGLE_OAUTH_CLIENT_ID oder _SECRET zu setzen, ist ein Startfehler, kein stilles No-Op – das gehört an den Proxy.

Image bauen

.github/workflows/build.yml führt die Tests aus, baut das Image und veröffentlicht es in GitHub Container Registry. Es deployiert nicht – das Deployment übernimmt ein separater Workflow oder ein separates Repository.

Veröffentlicht als ghcr.io/ramzpat/image-gen-mcp. Gericht nichts konfiguriert werden: der Workflow authentifiziert sich mit dem built-in GITHUB_TOKEN.

Verwendung in einem Deploy-Workflow

Deploy per Digest, nicht per Tag. Ein Pull-through-Cache vor einem mutierbaren Tag wie :latest liefert gerne ein vorheriges Image aus; ein Digest kann nicht fehlerhaft werden. Jeder Lauf gibt den Digest in der Job-Zusammenfassung aus, und der Workflow ist aufrufbar, wenn du bauen und deployen in einem Pipeline möchtest:

jobs:
  build:
    uses: ramzpat/image-gen-mcp/.github/workflows/build.yml@main
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploying ${{ needs.build.outputs.image }}@${{ needs.build.outputs.digest }}"

Aus einem separaten Repository löst du den Digest stattdessen zur Deploy-Zeit auf:

DIGEST=$(docker buildx imagetools inspect \
  ghcr.io/ramzpat/image-gen-mcp:latest --format '{{.Manifest.Digest}}')

Das GHCR-Paket ist standardmäßig privat. Ein Deploy-Job in einem anderen Repository benötigt entweder ein PAT mit read:packages oder das Paket in den Paketeinstellungen auf „public“.

Bereitstellung

Deployt von cloudrun-mcp-deployment (.github/workflows/deploy-image-gen-mcp.yml), das dieses Image als Backend-Container eines Cloud-Run-Multi-Container-Dienstes mit mcp-oauth-proxy davor ausführt. Dieses Repo besitzt das GCP-Projekt, die Region, die Allowlist und die Secrets; dieses hier veröffentlicht nur das Image.

Was dieses Deployment an diesem Container setzt:

HOST=0.0.0.0 statt Loopback ist erforderlich, kein Leak: „der Start-Prober von Cloud Run läuft außerhalb des Netzwerk-Namespace des Containers und kann einen Loopback-only-Socket nicht erreichen. Nur der Container, der --port deklariert (der Proxy), erhält ingress; bleibt das Backend von außerhalb extern unreachable.

Cloud Storage für 2K/4K

gcloud storage buckets create gs://BUCKET --uniform-bucket-level-access
gcloud storage buckets update gs://BUCKET \
  --lifecycle-file=<(echo '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}')

# The runtime service account signs URLs through the IAM Credentials API,
# because it has no private key file. It needs this role *on itself*:
gcloud iam service-accounts add-iam-policy-binding RUNTIME_SA \
  --member="serviceAccount:RUNTIME_SA" --role=roles/iam.serviceAccountTokenCreator
gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member="serviceAccount:RUNTIME_SA" --role=roles/storage.objectAdmin

Die Möglichkeit des serviceAccountTokenCreator-Timeout-Bundings in der echten Welt Vorgehensweise, mit der signierte URLs kaputt ausgeliefert werden.

Tests

uv run pytest -q

57 Tests: Absicherungen beim Start, Identitätsauflösung in beiden Formen (Proxy-Header, definiertes Token, wobei jede die Anmeldedaten des Ignoriert), Tool-Validierung und Auslieferung sowie End-to-End-Smoke-Tests, die einen echten MCP-Client über echtes HTTP und gegen uvicorn betreiben – im Stehmodus und im proxed Produktionsziel.

Kosten

Jeder Allowlistierte Benutzer nutz einen API-Key. Die Steuerungs- und Maßeartungen: --max-instances, IMAGE_MCP_MAX_CONCURRENCY, ein GCP-Budget-Alarm und IMAGE_MCP_RATE_PER_HOUR. Das Rate-Limit wird pro Instanz gezählt, effektiv ist also IMAGE_MCP_RATE_PER_HOUR × --max-instances.