Gemini Image MCP

Ein MCP-Server zum Erstellen und Bearbeiten von Bildern mit Googles Gemini-Bildmodellen (Nano Banana, Nano Banana 2, Nano Banana Pro). Er stellt ein Tool namens generate_image bereit, das KI-Tools wie Claude, Codex und Cline mit Ihrem eigenen API-Schlüssel aufrufen können.

Was es tut

• generate_image verarbeitet Text-zu-Bild sowie Bearbeitung und Komposition, wenn Sie Referenzbilder (lokale Dateipfade oder base64) übergeben.

• Jeder Erstellungsparameter ist pro Aufruf einstellbar: temperature (1), topP (0,95), topK, maxOutputTokens (65536 für Flash/Lite, 32768 für Pro), seed, stopSequences, presencePenalty, frequencyPenalty, systemInstruction, thinkingLevel (minimal/hoch), thinkingBudget, enableGoogleSearch (Standard true), imageSize (512/1K/2K/4K), aspectRatio („auto“ als Standard + Standard-Seitenverhältnisse), personGeneration.

• Enthält einen instructions-Block und Beschreibungen pro Parameter, damit MCP-Clients das Tool ohne zusätzliche Aufforderung nutzen können.

• Speichert Bilder auf der Festplatte und gibt Dateipfade zurück. Kein base64 in der Antwort, sodass ein 4K-Bild den Kontextfenster des Clients nicht überlastet.

• Fehler werden mit Hinweisen zurückgegeben (falscher Schlüssel, Ratenlimit, Sicherheitsblock, unbekanntes Modell) anstatt mit einem rohen API-Dump.

• stdio-Transport, die übliche Einrichtung für lokale MCP-Server.

Voraussetzungen

• Bun 1.0+

• Ein Gemini-API-Schlüssel von https://aistudio.google.com/apikey

Installation

bun install

Konfiguration

Drei Umgebungsvariablen, normalerweise in der Konfiguration des MCP-Clients gesetzt:

Modelle, die Sie auswählen können:

Modelle können auch mit dem Präfix models/ angegeben werden (z. B. models/gemini-3.1-flash-image).

Client-Einrichtung

Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

Von npm (bunx/npx)

Sobald das Paket veröffentlicht ist, richten Sie Ihren Client stattdessen auf bunx:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

generate_image-Parameter

Nur prompt ist erforderlich. Alles andere hat sinnvolle Standardwerte für die Bilderzeugung.

Das Tool gibt eine Textzusammenfassung mit den gespeicherten Dateipfaden, dem Modell, der effektiven Konfiguration und der Token-Nutzung zurück. Es gibt niemals Bilddaten inline zurück; öffnen Sie die Datei, um das Ergebnis zu sehen.

Dinge, die Sie Ihre KI fragen können

• „Erstelle ein 16:9-Heldenbild einer regnerischen Tokioter Straße bei Nacht, filmische Neonbeleuchtung.“

• „Bearbeite /tmp/product.png: platziere es auf einem Marmortisch mit weichem Morgenlicht“ (dies verwendet referenceImages).

• „Erstelle ein 4K-Poster mit der genauen Überschrift ‚LAUNCH DAY‘ mit gemini-3-pro-image.“

Entwicklung

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

Fehlerbehebung

• „Fehlender Gemini-API-Schlüssel“: setzen Sie GEMINI_API_KEY im env-Block der MCP-Konfiguration des Clients. Die Einstellung in Ihrer Shell reicht für GUI-Apps wie Claude Desktop nicht aus, da diese Ihre Shell-Umgebung nicht lesen.

• Sicherheitsblöcke: formulieren Sie den Prompt um. Wenn Personen beteiligt sind, überprüfen Sie personGeneration.

• 429 / Kontingent überschritten: warten Sie und wiederholen Sie den Vorgang, oder verwenden Sie gemini-3.1-flash-image, das das höhere Kontingent hat.

• Protokolle: Der Server schreibt Protokolle nur auf stderr. stdout transportiert das MCP-Protokoll, fügen Sie daher kein console.log hinzu.

Autor

Thomi Jasir dev@venobi.com

Lizenz

MIT