mcp-alphabanana

Englisch | 日本語

mcp-alphabanana ist ein Model Context Protocol (MCP) Server zur Generierung von Bild-Assets mit Google Gemini. Er wurde für MCP-kompatible Clients und Agenten-Workflows entwickelt, die eine schnelle Bildgenerierung, transparente Ausgaben, Referenzbild-Steuerung und flexible Bereitstellungsformate benötigen.

Schlüsselwörter: MCP-Server, Model Context Protocol, Gemini AI, Bildgenerierung, FastMCP

Hauptfunktionen:

• Ultraschnelle Gemini-Bildgenerierung über Flash- und Pro-Stufen hinweg

• Transparente PNG/WebP-Asset-Ausgabe für Web- und Spiele-Pipelines

• Multi-Bild-Stilsteuerung mit lokalen Referenzbilddateien

• Flexible Datei-, Base64- oder kombinierte Ausgaben für Agenten-Workflows

Schnellstart

Starten Sie den MCP-Server mit npx:

npx -y @tasopen/mcp-alphabanana

Oder fügen Sie ihn Ihrer MCP-Konfiguration hinzu:

{
  "mcp": {
    "servers": {
      "alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Setzen Sie GEMINI_API_KEY, bevor Sie den Server starten.

Für Claude Desktop: Laden Sie mcp-alphabanana-latest.mcpb herunter und fügen Sie es dann als Erweiterung in den Claude Desktop-Einstellungen hinzu. Für Windows wird empfohlen, die 'FileSystem'-Erweiterung für eine bessere lokale Dateiverwaltung hinzuzufügen.

Claude Registry

Die Claude-Registry / MCPB-Paket-Metadaten sind in manifest.json definiert und werden mit dem statischen 512x512-Icon unter images/mcp-alphabanana.png ausgeliefert.

Native sharp-Laufzeitpakete sind als optionale Abhängigkeiten deklariert, sodass .mcpb-Installationen die korrekte vorgefertigte Binärdatei auf jeder unterstützten Plattform auflösen können, ohne auf Postinstall-Hooks angewiesen zu sein.

• Stabiler MCPB-URL: https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb

• Versioniertes MCPB-URL-Muster: https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb

• Support: GitHub Issues

MCP-Server

Dieses Repository stellt einen MCP-Server bereit, der es KI-Agenten ermöglicht, Bilder mit Google Gemini zu generieren.

Er kann mit MCP-kompatiblen Clients verwendet werden, wie zum Beispiel:

• Claude Desktop

• VS Code MCP

• Cursor

Erstellt mit FastMCP 3 für eine vereinfachte Codebasis und flexible Ausgabeoptionen.

Glama MCP Server Badge:\

Verfügbare Tools

generate_image

Generiert Bilder mit Google Gemini mit optionaler Transparenz, lokalen Referenzbildern, Grounding und Reasoning-Metadaten.

Für Claude Desktop bevorzugen Sie outputType=file für mittlere oder große Bilder. base64- und combine-Antworten verbrauchen Claude-Kontext und können das Größenlimit des Clients erreichen. Verwenden Sie unter Windows die FileSystem-Erweiterung, um einen beschreibbaren absoluten outputPath und beliebige lokale referenceImages-Pfade auszuwählen.

Hauptparameter:

• prompt (string): Beschreibung des zu generierenden Bildes

• model: Flash3.1, Flash2.5, Pro3, flash, pro

• outputWidth und outputHeight: gewünschte endgültige Bildgröße in Pixeln im normalen Modus

• noresize + aspectRatio + output_resolution: gibt die native Gemini-Größe ohne Größenänderung zurück

• output_resolution: 0.5K, 1K, 2K, 4K

• output_format: png, jpg, webp

• outputType: file, base64, combine

• outputPath: erforderlich, wenn outputType file oder combine ist

• transparent: aktiviert transparente PNG/WebP-Nachbearbeitung

• referenceImages: optionales Array lokaler Referenzbilddateien

• grounding_type und thinking_mode: erweiterte Gemini 3.1-Steuerungen

Modellauswahl

Parameter

Vollständige Parameterreferenz für das generate_image-Tool.

Warum alphabanana?

• Keine Wasserzeichen: API-native saubere Bilder.

• Thinking/Grounding-Unterstützung: Höhere Prompt-Einhaltung und suchbasierte Genauigkeit.

• Produktionsbereit: Unterstützt transparentes WebP und exakte Seitenverhältnisse für Web- und Spiele-Assets.

Funktionen

• Ultraschnelle Bildgenerierung (Gemini 3.1 Flash, 0.5K/1K/2K/4K)

• Erweitertes Multi-Bild-Reasoning (bis zu 14 Referenzbilder)

• Thinking/Grounding-Unterstützung (nur Flash3.1)

• Transparente PNG/WebP-Ausgabe (Farbschlüssel-Nachbearbeitung, Despill)

• Mehrere Ausgabeformate: Datei, Base64 oder beides

• Flexible Größenänderungsmodi: crop, stretch, letterbox, contain

• Mehrere Modellstufen: Flash3.1, Flash2.5, Pro3, Legacy-Aliase

Beispielausgaben

Diese Beispielausgaben wurden mit mcp-alphabanana generiert und in images/examples gespeichert.

Konfiguration

Konfigurieren Sie den GEMINI_API_KEY in Ihrer MCP-Konfiguration (zum Beispiel mcp.json).

Beispiele:

• Referenzieren Sie eine OS-Umgebungsvariable aus mcp.json:

{
  "env": {
    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
  }
}

• Geben Sie den Schlüssel direkt in mcp.json an:

{
  "env": {
    "GEMINI_API_KEY": "your_api_key_here"
  }
}

VS Code Integration

Fügen Sie dies zu Ihren VS Code-Einstellungen (.vscode/settings.json oder Benutzereinstellungen) hinzu und konfigurieren Sie den Server env in mcp.json oder über die VS Code MCP-Einstellungen.

{
  "mcp": {
    "servers": {
      "mcp-alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Optional: Legen Sie ein benutzerdefiniertes Fallback-Verzeichnis für Schreibfehler fest, indem Sie MCP_FALLBACK_OUTPUT zum env-Objekt hinzufügen.

Nutzungsbeispiele

Grundlegende Generierung

{
  "prompt": "A pixel art treasure chest, golden trim, wooden texture",
  "model": "Flash3.1",
  "outputFileName": "chest",
  "outputType": "base64",
  "outputWidth": 64,
  "outputHeight": 64,
  "transparent": true
}

Native Größe ohne Größenänderung

{
  "prompt": "A clean app icon with a banana mascot, flat graphic design",
  "model": "Flash3.1",
  "outputFileName": "banana-icon-native",
  "outputType": "base64",
  "noresize": true,
  "aspectRatio": "1:1",
  "output_resolution": "0.5K",
  "output_format": "png"
}

Dieser Modus gibt die native Gemini-Pixelgröße für das angeforderte Verhältnis und die Auflösung zurück. Zum Beispiel gibt 1:1 + 0.5K 512x512 ohne Größenänderungsschritt zurück.

Erweitert (Vertikales Poster und Thinking)

{
  "prompt": "A vertical, photorealistic travel poster advertising Magical Wings Day Tours. A joyful young couple flies high above a breathtaking European countryside at golden hour, holding hands as they soar through a partly cloudy sky. Below them are vineyards, villages, forests, a winding river, and a hilltop medieval castle. The poster uses large, elegant typography with the headline FLY THE COUNTRYSIDE at the top and Magical Wings Day Tours branding near the bottom.",
  "model": "Flash3.1",
  "output_resolution": "1K",
  "outputFileName": "photoreal-travel-poster",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 848,
  "outputHeight": 1264,
  "output_format": "jpg",
  "thinking_mode": "high",
  "include_metadata": true
}

Grounding-Beispiel (Suchbasiert)

{
  "prompt": "A modern travel poster featuring today's weather and skyline highlights in Kuala Lumpur",
  "model": "Flash3.1",
  "outputFileName": "kl_travel_poster",
  "outputType": "base64",
  "outputWidth": 1024,
  "outputHeight": 1024,
  "grounding_type": "text",
  "thinking_mode": "high",
  "include_metadata": true,
  "include_thoughts": true
}

Dieses Beispiel aktiviert das Google-Suche-Grounding und gibt Grounding- und Reasoning-Metadaten in JSON zurück.

Mit Referenzbildern

{
  "prompt": "Use the reference image to create a game screen showing an opened treasure chest filled with coins and treasure, 8-bit dungeon crawler style, after-battle reward scene, dungeon corridor background, four-party status UI at the bottom",
  "model": "Flash3.1",
  "output_resolution": "0.5K",
  "outputFileName": "reference-image-dungeon-loot",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 600,
  "outputHeight": 448,
  "output_format": "webp",
  "transparent": false,
  "referenceImages": [
    {
      "description": "Treasure chest style reference",
      "filePath": "/path/to/references/pixel-art-treasure-chest.png"
    }
  ]
}

Transparenz & Ausgabeformate

• PNG: Volle Alpha, Farbschlüssel + Despill

• WebP: Volle Alpha, bessere Komprimierung (Flash3.1+)

• JPEG: Keine Transparenz (fällt auf soliden Hintergrund zurück)

Entwicklung

# Development mode with MCP CLI
npm run dev

# MCP Inspector (Web UI)
npm run inspect

# Build for production
npm run build

Lizenz

MIT