nano-banana-mcp

Un servidor del Protocolo de Contexto de Modelo para generación y edición de imágenes con IA mediante los modelos de imagen "Nano Banana" de Google Gemini, a través de la API de Interactions. Genera, edita y itera imágenes directamente desde Claude Code, Claude Desktop, Cursor o cualquier cliente compatible con MCP, con edición en múltiples turnos, fundamentación de búsqueda, storyboards intercalados, conjuntos de iconos de estilo consistente e imágenes a partir de video.

GitHub

Prueba este MCPPatrocinado

Documentación

nano-banana-mcp

Un servidor de Model Context Protocol para generación y edición de imágenes con IA usando los modelos de imagen Gemini "Nano Banana" de Google, a través de la Interactions API.

Genera, edita e itera sobre imágenes directamente desde Claude Code, Claude Desktop, Cursor o cualquier cliente compatible con MCP — con edición multi-turno, grounding de búsqueda, storyboards intercalados, conjuntos de iconos con estilo consistente e imagen desde video.

Photorealistic product shot of a teal ceramic coffee mug Isometric illustration of a developer workstation Kawaii banana sticker wearing sunglasses

Todo generado por este servidor — una foto de producto fotorrealista, una ilustración isométrica con texto legible y una pegatina vectorial. Sin ediciones.

Nota: Este servidor utiliza la Interactions API de Gemini, que actualmente está en beta. Los modelos de imagen Gemini 3 (gemini-3-pro-image, gemini-3.1-flash-image) pueden requerir acceso en tu clave de API. El nivel nano (gemini-2.5-flash-image) es el más ampliamente disponible. Consulta Requisitos.

Características

Texto a imagen — imágenes de alta calidad desde un prompt, hasta 4K, con control de relación de aspecto y resolución
Edición multi-turno — itera conversacionalmente; cada resultado devuelve un interaction_id que pasas de vuelta para seguir editando
Imágenes de referencia — hasta 14 entradas para prueba virtual, colocación de productos, composición, transferencia de estilo, restauración de fotos, reemplazo de atributos, maquetas 2D→3D
Grounding de búsqueda — fundamenta imágenes en datos en tiempo real (clima, noticias, resultados) con Google Search y Google Image Search
Historias intercaladas — un prompt → una secuencia de imágenes con subtítulos (storyboards, cómics, recetas, explicadores ilustrados)
Conjuntos de iconos con estilo consistente — generación encadenada que mantiene una apariencia uniforme en un conjunto de iconos
Imagen desde video — genera miniaturas/pósters desde una URL pública de YouTube
Vistas previas en línea — vistas previas reducidas devueltas al cliente para que el modelo pueda ver lo que generó y autocorregirse
Robusto — reintentos automáticos con backoff en límites de tasa y errores transitorios; mensajes de error claros y accionables

Inicio rápido

1. Obtén una clave de API de Gemini

Crea una clave en Google AI Studio.

2. Instalación

git clone https://github.com/petrkindlmann/nano-banana-mcp.git
cd nano-banana-mcp
npm install

3. Regístrate con tu cliente MCP

Claude Code

claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=your_key_here \
  -- node /absolute/path/to/nano-banana-mcp/index.js

Claude Desktop / Cursor / Windsurf / VS Code

Añade a tu configuración MCP (p. ej. ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/nano-banana-mcp/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

Reinicia tu cliente. Las cinco herramientas siguientes aparecerán.

Configuración

Variable de entorno	Requerida	Descripción
`GEMINI_API_KEY`	✅	Tu clave de API de Gemini.
`NANO_BANANA_MODEL_NANO`	—	Sobrescribe el ID de modelo del nivel `nano`.
`NANO_BANANA_MODEL_FLASH`	—	Sobrescribe el ID de modelo del nivel `flash`.
`NANO_BANANA_MODEL_PRO`	—	Sobrescribe el ID de modelo del nivel `pro`.

Los IDs de modelo son modelos beta/preview que Google rota y ocasionalmente retira. Si se lanza una versión más nueva — o un ID configurado queda obsoleto — apunta un nivel a un nuevo modelo sin editar código:

"env": {
  "GEMINI_API_KEY": "your_key_here",
  "NANO_BANANA_MODEL_FLASH": "gemini-3.2-flash-image"
}

Cada nivel mantiene su perfil de capacidades (tamaños, relaciones de aspecto, grounding) independientemente del ID que le asignes.

Uso

Solo pregunta en lenguaje natural — tu cliente MCP elige la herramienta y los argumentos correctos.

Tú: Genera una imagen hero 16:9 de un bosque de pinos brumoso al amanecer, cinematográfica, guárdala en hero.jpg

Claude: llama a generate_image → guarda hero.jpg, devuelve un interaction_id y una vista previa

Tú: Haz la niebla más densa y añade un ciervo en el claro

Claude: llama a edit_image con el interaction_id anterior → hero-v2.jpg

La edición multi-turno es la forma recomendada de iterar: cada resultado lleva un interaction_id, y pasarlo de vuelta mantiene el contexto completo de la conversación para que las ediciones se mantengan consistentes.

Herramientas

Herramienta	Descripción
`generate_image`	Genera una sola imagen desde un prompt de texto. Grounding de búsqueda opcional, pensamiento y control de aspecto/tamaño.
`edit_image`	Edita o itera sobre una imagen — encadena vía `previous_interaction_id`, o pasa imágenes de referencia desde disco.
`generate_story`	Genera texto + imágenes intercalados desde un prompt (storyboards, cómics, recetas, explicadores).
`generate_icon_set`	Genera un conjunto de iconos con estilo consistente mediante generación encadenada.
`generate_from_video`	Genera una imagen desde una URL pública de video de YouTube (solo modelo flash).

Modelos

Nivel	ID de modelo	Tamaños	Grounding de búsqueda	Pensamiento	Entrada de video	Salida JPEG
`nano`	`gemini-2.5-flash-image`	1K	—	—	—	— (solo PNG)
`flash`	`gemini-3.1-flash-image`	0.5K, 1K, 2K, 4K	web + imagen	—	✅	✅
`pro`	`gemini-3-pro-image`	1K, 2K, 4K	web	✅	—	✅

¿Cuál debería usar?

flash (predeterminado) — tu opción principal. El mejor equilibrio general entre calidad, costo y latencia. Hasta 4K, grounding de búsqueda, las relaciones de aspecto más amplias (21:9, 1:4, etc.), y el único nivel que acepta entrada de video.
pro — el renderizador de mayor calidad. Úsalo para activos profesionales/entregables, instrucciones complejas con múltiples elementos y texto legible renderizado dentro de la imagen (infografías, pósters, menús). Un paso de "Pensamiento" integrado refina la composición antes de renderizar. Más lento y más caro.
nano — velocidad y volumen. Solo 1K, sin grounding/pensamiento, siempre devuelve PNG. Recurre a él cuando generes muchas imágenes rápido y la calidad por imagen importe menos.

generate_story por defecto usa pro (mejor calidad intercalada); generate_from_video está bloqueado a flash (el único nivel que acepta video).

`generate_image`

Argumento	Tipo	Predeterminado	Notas
`prompt`	string	—	Requerido. Qué generar.
`output`	string	—	Requerido. Ruta del archivo de salida. La extensión elige el formato: `.png` (predeterminado) o `.jpg` (solo flash/pro — nano siempre devuelve PNG).
`model`	`nano`/`flash`/`pro`	`flash`	Nivel de modelo.
`ratio`	string	`1:1`	p. ej. `16:9`, `9:16`, `4:3`; `21:9`/`1:4`/`4:1`/`1:8`/`8:1` son solo flash.
`size`	`0.5K`/`1K`/`2K`/`4K`	`1K`	`0.5K` es solo flash.
`use_search`	boolean	`false`	Fundamenta con Google Search (flash/pro).
`use_image_search`	boolean	`false`	También usa Google Image Search como contexto visual (flash).
`show_thinking`	boolean	`false`	Incluye los resúmenes de pensamiento del modelo (pro).
`preview`	boolean	`true`	Devuelve una imagen de vista previa pequeña al cliente.

Devuelve la ruta del archivo y un interaction_id — pásalo a edit_image para seguir iterando.

`edit_image`

Los mismos controles de imagen que generate_image, más:

Argumento	Tipo	Notas
`previous_interaction_id`	string	Continúa una generación/edición anterior conversacionalmente (la forma recomendada de iterar).
`reference_images`	string[]	Rutas a imágenes de referencia en disco (máx. 14; flash: 10 objetos + 4 personajes, pro: 6 + 5).

`generate_story`

Argumento	Tipo	Predeterminado	Notas
`prompt`	string	—	Requerido. p. ej. "Un storyboard de 6 paneles de un zorro aprendiendo a volar, ilustraciones intercaladas con subtítulos."
`output_dir`	string	—	Requerido. Directorio para las imágenes numeradas.
`basename`	string	`story`	Prefijo del nombre de archivo.
`model`	`nano`/`flash`/`pro`	`pro`	`pro` da la mejor calidad intercalada.
`ratio` / `size`	string	—	Opcional; omítelos para dejar que el modelo decida.

`generate_icon_set`

Argumento	Tipo	Predeterminado	Notas
`prompts`	string[]	—	Requerido. Un prompt por icono.
`output_dir`	string	—	Requerido. Los archivos se nombran según cada prompt (`icon-shopping-cart.png`).
`model`	`nano`/`flash`/`pro`	`flash`
`size`	`0.5K`/`1K`/`2K`/`4K`	`1K`

`generate_from_video`

Argumento	Tipo	Predeterminado	Notas
`youtube_url`	string	—	Requerido. URL pública de YouTube.
`prompt`	string	—	Requerido. Qué generar desde el video.
`output`	string	—	Requerido. Ruta del archivo de salida.
`ratio`	string	`16:9`
`size`	`0.5K`/`1K`/`2K`/`4K`	`1K`
`preview`	boolean	`true`

Consejos de prompts

Para mejores resultados, escribe oraciones completas que describan sujeto + entorno + iluminación + cámara/lente + ambiente — ritmo narrativo en lugar de sopa de palabras clave.

Un retrato fotorrealista en primer plano de un ceramista japonés anciano con arrugas profundas y una sonrisa cálida. Luz suave de hora dorada entrando por una ventana. Capturado con un lente retrato de 85mm, fondo con bokeh suave. Ambiente sereno y magistral.

Requisitos

Node.js 18+ (usa el ejecutor node:test integrado y módulos ES modernos)
Una clave de API de Gemini (GEMINI_API_KEY)
La Interactions API está en beta; los niveles de imagen Gemini 3 (flash, pro) pueden requerir acceso. El nivel nano es el más ampliamente disponible — establece model: "nano" si flash/pro no están disponibles en tu clave.

Desarrollo

npm test          # unit tests (node:test) — no API key needed
npm run smoke     # live smoke test — requires GEMINI_API_KEY

El código está dividido en módulos enfocados:

lib/config.js — tablas de modelos, validación de relación de aspecto/tamaño, ayudantes
lib/gemini.js — cliente API, reintentos, extracción de respuestas, vistas previas
lib/tools.js — esquemas y manejadores de herramientas
index.js — conexión del servidor MCP

Licencia

MIT