nano-banana-mcp

Servidor MCP (Model Context Protocol) en TypeScript que expone Nano Banana —el modelo de imagen Gemini 2.5 Flash Image de Google— a Claude. Permite generar, editar y componer imágenes desde Claude Desktop, Claude Code o cualquier cliente MCP.

Capacidades (tools)

Tool	Descripción	Entradas
generate_image	Texto → imagen	prompt
edit_image	Imagen + texto → imagen (inpainting, estilo, retoques)	prompt, image
compose_images	N imágenes + texto → imagen (fusión, composición, transferencia de estilo)	prompt, images[]

Las imágenes de entrada (image / images) aceptan: ruta a archivo local, data URL (data:image/png;base64,...) o base64 crudo. Las imágenes de salida se devuelven inline en base64 en la respuesta del tool.

Requisitos

• Node.js >= 18
• Una API key de Google AI Studio: https://aistudio.google.com/apikey

Instalación

npm install
npm run build

Copia .env.example a .env y coloca tu key:

cp .env.example .env
# edita .env -> GEMINI_API_KEY=...

El .env es solo para desarrollo local. Al conectarlo a un cliente MCP, la key se pasa por la variable de entorno del propio cliente (ver abajo).

Conectar a Claude

Claude Code (CLI)

claude mcp add nano-banana \
  -e GEMINI_API_KEY=tu_api_key \
  -- node /ruta/absoluta/nano-banana-mcp/dist/index.js

Claude Desktop

Edita claude_desktop_config.json:

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/ruta/absoluta/nano-banana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "tu_api_key"
      }
    }
  }
}

Reinicia el cliente y pídele, por ejemplo: "genera una imagen de un gato astronauta en acuarela".

Desarrollo

npm run dev        # ejecuta con tsx (sin compilar)
npm run typecheck  # verifica tipos
npm run build      # compila a dist/

Prueba rápida del protocolo (sin key, solo lista tools):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js

Configuración

Variable	Requerida	Por defecto	Descripción
GEMINI_API_KEY	Sí	—	API key de Google AI Studio
NANO_BANANA_MODEL	No	gemini-2.5-flash-image	Modelo de imagen a usar

Ambientes

La configuración por ambiente (local / integración / QA / producción) está documentada en docs/environments/. Las decisiones de arquitectura en docs/architecture/.

Notas

• En un servidor stdio, stdout está reservado para el protocolo MCP; los logs de diagnóstico van a stderr.
• Nunca comitees tu .env ni la API key (ya está en .gitignore).