Nano Banana en Claude Code: skill o MCP con modelos vigentes

Qué hace falta para que Claude Code cree imágenes con Nano Banana

Claude no genera imágenes raster por sí mismo: escribe código, SVG y texto, pero no píxeles (lo explica con más detalle ¿Puede Claude generar imágenes?). Lo que sí puede hacer Claude Code es ejecutar algo que llame a la Gemini API, donde está Nano Banana, y guardar el PNG resultante en tu proyecto. Para que eso funcione a 24 de septiembre de 2026 necesitas tres cosas:

1. Un ID de modelo que siga encendido. En la Gemini API son gemini-3.1-flash-image (Nano Banana 2), gemini-3-pro-image (Nano Banana Pro) y gemini-3.1-flash-lite-image (Nano Banana 2 Lite). Los ID -preview de Nano Banana 2 y Pro se apagaron el 25 de junio de 2026, y gemini-2.5-flash-image se apaga el 2 de octubre de 2026 (calendario de bajas de la Gemini API).
2. Una clave de Google AI Studio con la facturación activada. Estos tres modelos no tienen nivel gratuito en la API (precios de la Gemini API). La clave va en una variable de entorno, nunca pegada en la conversación.
3. Un puente entre Claude y la API: una skill que ejecuta un script, o un servidor MCP que expone una herramienta. Las dos rutas están más abajo, con los comandos completos.

Si seguiste un vídeo o un repositorio de principios de 2026 y ahora Claude te contesta con un error en lugar de una imagen, lo más probable es que tu configuración apunte a uno de los ID apagados. La tabla de la sección siguiente te dice cuál y qué cambiar.

Skill o servidor MCP: cómo elegir

Las dos rutas terminan en la misma llamada a Google, pero cambian quién controla los parámetros y qué tienes que mantener.

Elige la skill si quieres cabeceras de blog, miniaturas o recursos web con un formato concreto y guardados donde los espera tu proyecto: controlas modelo, proporción y ruta, y el código es tuyo. Elige el servidor MCP si ya usabas la extensión de Gemini CLI y te interesan sus herramientas específicas (restaurar fotos, iconos, patrones, diagramas, secuencias de hasta 8 variaciones) más que el formato exacto.

Hay dos atajos más. Pegar la clave en el chat para que Claude la guarde en un archivo, como propone la guía de Ryan Doser con OpenRouter, funciona, pero deja la clave en el historial de la sesión. Y los servidores MCP alojados por terceros o las skills de catálogos reciben tus prompts, tus imágenes de referencia y, a menudo, tu clave: es una decisión de confianza sobre ese proveedor, no un detalle de instalación.

Por qué tu configuración de Nano Banana dejó de generar imágenes

Si tu configuración fija o hereda un ID que ya no existe en la Gemini API, Claude recibe un error donde esperaba una imagen. Estos son los casos habituales, con su estado a 24 de septiembre de 2026:

Fuentes: el código de la extensión (imageGenerator.ts, con el último cambio en main del 7 de marzo de 2026), el README de cc-nano-banana y el calendario de bajas de Google. Que la instalación por defecto de la extensión falle es una deducción de ese código: la variable acepta cualquier cadena sin validarla y, si no existe, usa el ID preview. El texto exacto del error que verás depende de la respuesta de Google; lo relevante es que la herramienta devuelve un fallo en lugar de un archivo.

Para localizar un ID retirado en tu máquina sin revisar archivo por archivo:

echo "$NANOBANANA_MODEL"
grep -n "image-preview\|2.5-flash-image" ~/.zshrc ~/.bashrc ~/.claude.json .mcp.json 2>/dev/null
grep -rn "image-preview\|2.5-flash-image" .claude/ ~/.claude/skills/ 2>/dev/null

Si aparece algún resultado, sustituye el ID por uno vigente en ese mismo sitio, abre una terminal nueva y vuelve a lanzar claude para que tome el entorno actualizado. Estas fechas son de la Gemini API; en Vertex AI el calendario es distinto (lo tienes en Nano Banana en Vertex AI: modelos vigentes, costes y errores).

Ruta recomendada: una skill con script de Python

Una skill de Claude Code es una carpeta con un SKILL.md (metadatos en YAML más instrucciones) que puede incluir scripts. Si la guardas en .claude/skills/ dentro del repositorio, se carga en las sesiones de ese proyecto y la compartes con tu equipo al hacer commit; en ~/.claude/skills/ queda disponible en todos tus proyectos de ese ordenador (documentación de skills).

Estructura y dependencias

.claude/skills/nano-banana/
├── SKILL.md
└── scripts/
    └── generate.py

Instala el SDK de Google en el Python que vaya a usar Claude y deja la clave en tu perfil de shell:

python3 -m pip install google-genai
echo 'export GEMINI_API_KEY="tu-clave-de-ai-studio"' >> ~/.zshrc

Si prefieres un entorno virtual, crea uno y escribe en SKILL.md la ruta de su intérprete (.venv/bin/python) en lugar de python3. Abre una terminal nueva antes de lanzar claude para que la variable exista en la sesión.

El script generate.py

El script admite los tres ID vigentes y nada más, lee la clave de GEMINI_API_KEY, pide a la API solo imagen (response_modalities=["IMAGE"]) y fija proporción y resolución con image_config. Con --input añade imágenes de referencia para editar o componer:

#!/usr/bin/env python3
"""Genera o edita una imagen con Nano Banana a través de la Gemini API.

Uso:
  python3 generate.py "prompt" --out images/hero.png [--model gemini-3.1-flash-image]
                      [--aspect 16:9] [--size 2K] [--input ref.png ...]
La clave se lee de GEMINI_API_KEY (nunca de la línea de comandos).
"""
import argparse
import os
import pathlib
import sys

from google import genai
from google.genai import types

MODELS = {
    "gemini-3.1-flash-lite-image",  # Nano Banana 2 Lite, solo 1K
    "gemini-3.1-flash-image",       # Nano Banana 2, 512/1K/2K/4K
    "gemini-3-pro-image",           # Nano Banana Pro, 1K/2K/4K
}

def main() -> int:
    p = argparse.ArgumentParser()
    p.add_argument("prompt")
    p.add_argument("--out", required=True)
    p.add_argument("--model", default="gemini-3.1-flash-image")
    p.add_argument("--aspect", default="1:1")
    p.add_argument("--size", default="1K")
    p.add_argument("--input", action="append", default=[])
    a = p.parse_args()

    if a.model not in MODELS:
        print(f"Unknown or retired model id: {a.model}. Use one of {sorted(MODELS)}", file=sys.stderr)
        return 2
    if not os.environ.get("GEMINI_API_KEY"):
        print("GEMINI_API_KEY is not set", file=sys.stderr)
        return 2

    contents = [a.prompt]
    for path in a.input:
        data = pathlib.Path(path).read_bytes()
        mime = "image/png" if path.lower().endswith(".png") else "image/jpeg"
        contents.append(types.Part.from_bytes(data=data, mime_type=mime))

    # Opcional: pasarela compatible con la Gemini API, p. ej. GEMINI_BASE_URL=https://api.laozhang.ai
    base_url = os.environ.get("GEMINI_BASE_URL")
    client = genai.Client(http_options=types.HttpOptions(base_url=base_url)) if base_url else genai.Client()
    resp = client.models.generate_content(
        model=a.model,
        contents=contents,
        config=types.GenerateContentConfig(
            response_modalities=["IMAGE"],
            image_config=types.ImageConfig(aspect_ratio=a.aspect, image_size=a.size),
        ),
    )

    for cand in resp.candidates or []:
        for part in (cand.content.parts if cand.content else []) or []:
            if part.inline_data and part.inline_data.data:
                out = pathlib.Path(a.out)
                out.parent.mkdir(parents=True, exist_ok=True)
                out.write_bytes(part.inline_data.data)
                print(f"saved {out} ({len(part.inline_data.data)} bytes)")
                return 0

    fb = getattr(resp, "prompt_feedback", None)
    reason = resp.candidates[0].finish_reason if resp.candidates else None
    print(f"No image returned. blockReason={getattr(fb, 'block_reason', None)} finishReason={reason}", file=sys.stderr)
    return 1

if __name__ == "__main__":
    sys.exit(main())

La lista cerrada de modelos es deliberada: si alguien escribe un ID retirado, el script lo rechaza antes de gastar una petición y el mensaje le dice qué usar. Cuando Google publique otro ID, añadirlo es cambiar una línea.

SKILL.md: cuándo y cómo lo usa Claude

La description es lo que Claude lee para decidir si carga la skill, así que debe nombrar las peticiones que la activan. El cuerpo fija las reglas que no quieres repetir en cada prompt:

---
name: nano-banana
description: Genera o edita imágenes raster (cabeceras de blog, miniaturas, iconos, fotos de producto) con Nano Banana mediante la Gemini API y las guarda en el proyecto. Úsala cuando el usuario pida crear, generar o editar una imagen PNG o JPG. No la uses para SVG ni para diagramas que se puedan escribir en código.
---

# Nano Banana

Ejecuta desde la raíz del proyecto:

python3 .claude/skills/nano-banana/scripts/generate.py "<prompt detallado>" --out <ruta/archivo.png> [--model <id>] [--aspect 16:9] [--size 2K] [--input <referencia.png>]

Reglas:
- Modelo por defecto: gemini-3.1-flash-image.
- gemini-3.1-flash-lite-image solo si el usuario pide rapidez o volumen, siempre con --size 1K y sin varias referencias.
- gemini-3-pro-image solo si el usuario lo pide o el encargo exige coherencia de marca estricta.
- Guarda en la carpeta de imágenes del proyecto con un nombre descriptivo. No sobrescribas un archivo existente sin preguntar.
- No pidas la clave API ni la escribas en comandos o archivos: el script la lee de GEMINI_API_KEY.
- Código de salida 2: muestra el mensaje y detente. Código 1 ("No image returned"): resume blockReason y finishReason y propón reformular el prompt.
- Antes de generar más de 5 imágenes en una misma tarea, di cuántas son y el coste aproximado.

Si guardas la skill en ~/.claude/skills/ en vez de en el proyecto, cambia la ruta del comando por ~/.claude/skills/nano-banana/scripts/generate.py. El nombre de la carpeta se convierte además en comando: /nano-banana la invoca directamente.

Primera prueba y códigos de salida

Con Claude Code abierto en tu proyecto, pide algo concreto: «Genera una cabecera 16:9 en 2K para el artículo sobre facturación electrónica y guárdala en public/images/facturacion-hero.png». Claude debería ejecutar el script con --aspect 16:9 --size 2K y responder con la línea saved ….

El script todavía no se ha probado generando una imagen real; lo comprobado son sus respuestas de error: sin GEMINI_API_KEY sale con código 2 y el mensaje GEMINI_API_KEY is not set; con gemini-3-pro-image-preview sale con código 2 y lista los tres ID válidos; con una clave falsa y un ID vigente, la petición llega a generativelanguage.googleapis.com y vuelve 400 INVALID_ARGUMENT con API_KEY_INVALID. Si ves ese último error con tu clave real, revisa que la hayas copiado entera y que el proyecto de AI Studio tenga la facturación activa. Si la API responde sin imagen, el diagnóstico sigue en Nano Banana no genera imagen en la API: diagnóstico y arreglo.

Para editar, pasa la foto original con --input y describe el cambio en el prompt. Nano Banana 2 y Pro admiten hasta 14 imágenes de referencia en una misma petición; Lite no está optimizado para varias referencias ni para ediciones encadenadas (documentación de generación de imágenes). Para redactar mejores instrucciones, Cómo escribir prompts para Nano Banana tiene plantillas por tipo de encargo.

Ruta MCP: la extensión nanobanana de Google en Claude Code

La extensión nanobanana de Gemini CLI es, por dentro, un servidor MCP por stdio. No necesitas Gemini CLI para usarla desde Claude Code: basta con compilar el servidor y registrarlo. El repositorio no incluye el código compilado (mcp-server/dist/), pero según su package.json, npm install en la raíz instala las dependencias y compila mcp-server/dist/index.js en un solo paso. Usa Node.js 20 o superior: el package.json acepta desde la 18, pero el README pide la 20.

git clone https://github.com/gemini-cli-extensions/nanobanana ~/mcp/nanobanana
cd ~/mcp/nanobanana && npm install

Después lo registras con la clave y, sobre todo, con un modelo vigente. Pon --transport stdio entre las opciones --env y el nombre del servidor: si el nombre va justo detrás de --env, la CLI lo interpreta como otra variable (documentación de MCP en Claude Code):

claude mcp add \
  --env NANOBANANA_API_KEY="$GEMINI_API_KEY" \
  --env NANOBANANA_MODEL=gemini-3.1-flash-image \
  --transport stdio nanobanana \
  -- node ~/mcp/nanobanana/mcp-server/dist/index.js

Sin --scope, el servidor se guarda en ámbito local: solo tú lo ves y solo en ese proyecto, dentro de ~/.claude.json, que no forma parte del repositorio. El valor de la clave queda escrito en ese archivo. Con --scope user lo tendrás en todos tus proyectos. Comprueba la conexión con claude mcp list (debe aparecer ✔ Connected) o con /mcp dentro de la sesión.

Para compartirlo con el equipo, .mcp.json admite variables de entorno con la sintaxis ${VAR}, de modo que cada persona usa su propia clave y ninguna acaba en Git:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["${HOME}/mcp/nanobanana/mcp-server/dist/index.js"],
      "env": {
        "NANOBANANA_API_KEY": "${GEMINI_API_KEY}",
        "NANOBANANA_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

Claude Code pide aprobación la primera vez que encuentra servidores de un .mcp.json en una sesión interactiva. Si ya tenías servidores configurados en Claude Desktop, claude mcp add-from-claude-desktop los importa (solo en macOS y WSL), pero revisa que ninguno arrastre un ID preview.

Lo que cambia frente a la skill: generate_image acepta prompt, número de variaciones (1 a 8), estilos, semilla y formato de salida, pero no proporción ni resolución; guarda los archivos en nanobanana-output/ bajo el directorio de trabajo del servidor (cuando lo lanza Claude Code, normalmente la carpeta del proyecto; si no aparecen ahí, búscala con find ~ -type d -name nanobanana-output) y devuelve a Claude las rutas, no la imagen. Eso último importa: Claude Code avisa cuando la salida de una herramienta MCP supera 10.000 tokens y la corta en 25.000 por defecto, límite que también se aplica a los datos de imagen (MAX_MCP_OUTPUT_TOKENS). Un servidor MCP que devuelva la imagen codificada dentro de la respuesta puede chocar con ese tope; uno que guarde en disco, no. Si lo que buscas es comparar este servidor con otros, Los mejores MCP para Claude Code que conviene instalar primero en 2026 recoge los habituales.

La clave API, fuera de la conversación

La extensión busca la clave en este orden y usa la primera que encuentre: NANOBANANA_API_KEY, NANOBANANA_GEMINI_API_KEY, NANOBANANA_GOOGLE_API_KEY, GEMINI_API_KEY y GOOGLE_API_KEY. Si tienes una clave antigua en NANOBANANA_GEMINI_API_KEY (la variable que indica cc-nano-banana) y una nueva en GEMINI_API_KEY, se usará la antigua; ese orden explica muchos «he cambiado la clave y sigue fallando».

Las tres formas razonables de guardar la clave son, de más simple a más compartible: una variable en tu perfil de shell (la skill la lee de ahí), la opción --env en ámbito local (queda en ~/.claude.json, fuera del repositorio) y ${GEMINI_API_KEY} dentro de .mcp.json (cada persona pone su valor). Lo que conviene evitar es pegarla en el chat: queda en el historial de la sesión y, si Claude la guarda en un archivo como APIs.env dentro del proyecto, añade ese archivo a .gitignore antes de tu próximo commit.

Cuánto cuesta cada imagen y por qué necesitas facturación

En la Gemini API, Nano Banana 2, Nano Banana 2 Lite y Nano Banana Pro aparecen como «Not available» en el nivel gratuito: sin facturación activada, la clave no genera imágenes con estos modelos. Precios del nivel de pago estándar, en dólares y por imagen de salida, a 24 de septiembre de 2026:

Cada imagen de referencia que envías suma unos 0,0011 $ con Pro, y el texto del prompt es un coste menor. Para hacer tu cuenta, multiplica imágenes por precio unitario. Veinte cabeceras 16:9 en 2K con Nano Banana 2 son 20 × 0,101 $ = 2,02 $; las mismas con Pro, 20 × 0,134 $ = 2,68 $; en 1K con Lite, 20 × 0,0336 $ ≈ 0,67 $. Con la ruta MCP, cada variación se cobra como una imagen, así que pedir 8 variaciones multiplica por 8. En el nivel de pago, Google indica que tus datos no se usan para mejorar sus productos, algo a tener en cuenta si trabajas con material de clientes. El desglose completo, con modo Batch incluido, está en Precio de Nano Banana API: Lite, Nano Banana 2, Pro, gratis y rutas, y para decidir qué modelo encaja con cada encargo, en Nano Banana 2 Lite vs 2 vs Pro: elige por tarea.

Si no puedes activar la facturación de Google, el script admite un endpoint compatible mediante GEMINI_BASE_URL. laozhang.ai sirve los mismos tres ID con el formato nativo de Gemini (/v1beta/models/{modelo}:generateContent) a precio fijo por llamada, sin depender de la resolución: 0,025 $ Lite, 0,055 $ Nano Banana 2 y 0,09 $ Pro. Para usarlo, pon GEMINI_BASE_URL=https://api.laozhang.ai y la clave de ese servicio en GEMINI_API_KEY; con una clave falsa, el script llega a su pasarela y recibe 401 Invalid token, así que la conexión está bien formada, pero la generación real por esa vía no está probada con este script. Ten en cuenta que es un tercero: no se aplican los términos de datos ni el SLA de Google, y no sirve para esquivar restricciones regionales.

Dónde no funciona: claude.ai, Cowork y sesiones en la nube

Todo lo anterior necesita un proceso local que ejecute el script o el servidor MCP, y eso delimita dónde funciona:

• Claude Code en tu terminal: funcionan las dos rutas.
• Pestaña Code de la app de escritorio, en sesión local: usa los mismos servidores MCP configurados en ~/.claude.json y .mcp.json.
• Chat de claude.ai: no ejecuta scripts de tu ordenador ni lanza servidores locales; ahí Claude puede describir o escribir SVG, no llamar a Nano Banana por ti.
• Cowork y sesiones en la nube (incluidas las rutinas): no leen ~/.claude/skills/. Cowork carga las skills activadas en tu cuenta de claude.ai (Customize, en la barra lateral de la app de escritorio). Las sesiones en la nube cargan además las skills versionadas en .claude/skills/ del repositorio, pero el script también necesita allí google-genai y la variable GEMINI_API_KEY; si ese entorno no los tiene, fallará con el código 2 descrito arriba.

Si todavía no tienes Claude Code instalado, empieza por Cómo instalar Claude Code; y si esta skill te ha servido de modelo, Las mejores skills de Claude Code para instalar primero en 2026 tiene otras que siguen el mismo patrón.

Preguntas frecuentes

¿Necesito instalar Gemini CLI para usar Nano Banana en Claude Code? No. La skill con script solo necesita Python y google-genai, y el servidor MCP de la extensión se ejecuta con Node.js sin Gemini CLI. Gemini CLI solo hace falta si usas cc-nano-banana, que delega en él.

¿Sirve la clave gratuita de Google AI Studio? Puedes crear la clave sin pagar, pero Nano Banana 2, 2 Lite y Pro no tienen nivel gratuito en la API: hasta que actives la facturación en el proyecto, las peticiones de imagen no saldrán adelante.

¿Las imágenes llevan marca de agua? Sí. Según la documentación de Google, todas las imágenes que generan estos modelos incluyen una marca de agua SynthID, también las que Claude guarda en tu proyecto.

¿Qué pasa con mi configuración de gemini-2.5-flash-image después del 2 de octubre de 2026? Dejará de responder en la Gemini API. Google recomienda pasar a gemini-3.1-flash-lite-image, que además es más barato (0,0336 $ por imagen 1K frente a 0,039 $); si necesitas 2K, 4K o varias referencias, usa gemini-3.1-flash-image.