mcp-alphabanana

Inglés | 日本語

mcp-alphabanana es un servidor del Protocolo de Contexto de Modelo (MCP) para generar recursos de imagen con Google Gemini. Está diseñado para clientes compatibles con MCP y flujos de trabajo de agentes que necesitan generación rápida de imágenes, salidas transparentes, guía mediante imágenes de referencia y formatos de entrega flexibles.

Palabras clave: Servidor MCP, Protocolo de Contexto de Modelo, Gemini AI, generación de imágenes, FastMCP

Capacidades clave:

• Generación de imágenes ultrarrápida con Gemini en los niveles Flash y Pro

• Salida de recursos PNG/WebP transparentes para flujos de trabajo web y de juegos

• Guía de estilo con múltiples imágenes mediante archivos de imagen de referencia locales

• Salidas flexibles en archivo, base64 o combinadas para flujos de trabajo de agentes

Inicio rápido

Ejecuta el servidor MCP con npx:

npx -y @tasopen/mcp-alphabanana

O añádelo a tu configuración de MCP:

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

Establece GEMINI_API_KEY antes de iniciar el servidor.

Para Claude Desktop, Descarga mcp-alphabanana-latest.mcpb, luego añádelo como extensión desde la configuración de Claude Desktop. Para Windows, se recomienda añadir la extensión 'FileSystem' para un mejor manejo de archivos locales.

Registro de Claude

El registro de Claude / metadatos del paquete MCPB se definen en manifest.json y se envían con el icono estático de 512x512 en images/mcp-alphabanana.png.

Los paquetes de tiempo de ejecución nativos de sharp se declaran como dependencias opcionales para que las instalaciones de .mcpb puedan resolver el binario precompilado correcto en cada plataforma compatible sin depender de hooks de postinstalación.

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

• Patrón de URL versionada de MCPB: https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb

• Soporte: GitHub Issues

Servidor MCP

Este repositorio proporciona un servidor MCP que permite a los agentes de IA generar imágenes usando Google Gemini.

Puede utilizarse con clientes compatibles con MCP como:

• Claude Desktop

• VS Code MCP

• Cursor

Construido con FastMCP 3 para una base de código simplificada y opciones de salida flexibles.

Insignia del servidor Glama MCP:\

Herramientas disponibles

generate_image

Genera imágenes usando Google Gemini con transparencia opcional, imágenes de referencia locales, fundamentación y metadatos de razonamiento.

Para Claude Desktop, prefiere outputType=file para imágenes medianas o grandes. Las respuestas base64 y combine consumen contexto de Claude y pueden alcanzar el límite de tamaño del cliente. En Windows, usa la extensión FileSystem para elegir una outputPath absoluta escribible y cualquier ruta de referenceImages local.

Parámetros clave:

• prompt (string): descripción de la imagen a generar

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

• outputWidth y outputHeight: tamaño final de imagen solicitado en píxeles en modo normal

• noresize + aspectRatio + output_resolution: devuelve el tamaño nativo de Gemini sin cambiar el tamaño

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

• output_format: png, jpg, webp

• outputType: file, base64, combine

• outputPath: requerido cuando outputType es file o combine

• transparent: habilita el postprocesamiento de PNG/WebP transparente

• referenceImages: matriz opcional de archivos de imagen de referencia locales

• grounding_type y thinking_mode: controles avanzados de Gemini 3.1

Selección de modelo

Parámetros

Referencia completa de parámetros para la herramienta generate_image.

¿Por qué alphabanana?

• Sin marcas de agua: Imágenes limpias nativas de la API.

• Soporte de Pensamiento/Fundamentación: Mayor adherencia a las instrucciones y precisión respaldada por búsqueda.

• Listo para producción: Admite WebP transparente y relaciones de aspecto exactas para recursos web y de juegos.

Características

• Generación de imágenes ultrarrápida (Gemini 3.1 Flash, 0.5K/1K/2K/4K)

• Razonamiento avanzado con múltiples imágenes (hasta 14 imágenes de referencia)

• Soporte de Pensamiento/Fundamentación (solo Flash3.1)

• Salida PNG/WebP transparente (postprocesamiento de clave de color, eliminación de bordes)

• Múltiples formatos de salida: archivo, base64 o ambos

• Modos de cambio de tamaño flexibles: recortar, estirar, letterbox, contener

• Múltiples niveles de modelo: Flash3.1, Flash2.5, Pro3, alias heredados

Ejemplos de salida

Estos ejemplos de salida se generaron con mcp-alphabanana y se almacenaron en images/examples.

Configuración

Configura GEMINI_API_KEY en tu configuración de MCP (por ejemplo, mcp.json).

Ejemplos:

• Referenciar una variable de entorno del SO desde mcp.json:

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

• Proporcionar la clave directamente en mcp.json:

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

Integración con VS Code

Añádelo a tu configuración de VS Code (.vscode/settings.json o configuración de usuario), configurando el env del servidor en mcp.json o a través de la configuración de MCP de VS Code.

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

Opcional: Establece un directorio de respaldo personalizado para fallos de escritura añadiendo MCP_FALLBACK_OUTPUT al objeto env.

Ejemplos de uso

Generación básica

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

Tamaño nativo sin cambio de tamaño

{
  "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"
}

Este modo devuelve el tamaño de píxel nativo de Gemini para la relación y resolución solicitadas. Por ejemplo, 1:1 + 0.5K devuelve 512x512 sin ningún paso de cambio de tamaño.

Avanzado (Póster vertical y pensamiento)

{
  "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
}

Muestra de fundamentación (respaldada por búsqueda)

{
  "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
}

Esta muestra habilita la fundamentación de Google Search y devuelve metadatos de fundamentación y razonamiento en JSON.

Con imágenes de referencia

{
  "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"
    }
  ]
}

Transparencia y formatos de salida

• PNG: Alfa completo, clave de color + eliminación de bordes

• WebP: Alfa completo, mejor compresión (Flash3.1+)

• JPEG: Sin transparencia (vuelve a un fondo sólido)

Desarrollo

# Development mode with MCP CLI
npm run dev

# MCP Inspector (Web UI)
npm run inspect

# Build for production
npm run build

Licencia

MIT