Generar imágenes en Gemini CLI: configuración de servidor MCP

Gemini CLI es el agente de terminal de código abierto de Google, y MCP es el protocolo que utiliza para acceder a herramientas externas. Conéctalo a un servidor MCP remoto y la misma sesión de chat que edita tu código podrá generar imágenes, video y voz, guardando los archivos directamente en tu directorio de trabajo.

Respuesta rápida: ejecuta gemini mcp add --transport http --scope user bananabanana https://bananabanana.pro/api/mcp -H "Authorization: Bearer $BB_KEY", acepta confiar en la carpeta cuando la CLI lo solicite y luego revisa gemini mcp list para ver el estado en verde Connected. Las imágenes cuestan desde $0.03 cada una, facturadas por generación desde tu saldo.

Todo lo que se describe a continuación se probó con Gemini CLI 0.55.1 el 17 de agosto de 2026, con una clave bb_live_… activa. Cuando la documentación oficial difiere del comportamiento real de la CLI, se menciona de forma explícita.

Configuración paso a paso

Solo dos comandos. El primero registra el servidor:

export BB_KEY=bb_live_…   # create one at https://bananabanana.pro/profile
 
gemini mcp add --transport http --scope user \
  bananabanana https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer $BB_KEY"

El segundo comprueba el estado:

gemini mcp list
# ✓ bananabanana: https://bananabanana.pro/api/mcp (http) - Connected

Si obtienes Disabled en lugar de Connected, lee la siguiente sección antes de tocar cualquier otra cosa. Esa sutileza me tomó cinco minutos resolverla.

Cinco detalles que la documentación no menciona

La confianza en la carpeta desactiva todo de forma silenciosa. Si ejecutas gemini mcp list en un directorio en el que la CLI no confía, verás esto:

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

○ bananabanana: https://bananabanana.pro/api/mcp (http) - Disabled

Observa la segunda línea: incluso un servidor configurado con --scope user permanece desactivado. La CLI te pide confirmación en el primer inicio interactivo; si estás automatizando mediante scripts, el estado de confianza reside en ~/.gemini/trustedFolders.json como un mapa de rutas con el valor TRUST_FOLDER. Es una decisión lógica, pero un modo de fallo confuso, ya que el estado "Disabled" no indica claramente que el problema sea la carpeta.

gemini mcp add escribe url, no httpUrl. La documentación describe httpUrl para Streamable HTTP. Lo que la CLI 0.55.1 generó en la práctica fue:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $BB_KEY" }
    }
  }
}

Ambos formatos conectan. Pero si comparas una configuración de la documentación con lo que generó la CLI, pensarás que una de ellas está rota. Ambas funcionan.

El alcance predeterminado es project, y ahí es donde va tu clave. Si omites --scope user, la clave terminará en .gemini/settings.json dentro de tu repositorio. Tras un simple git add ., quedará en tu historial. Usa siempre --scope user o mantén el encabezado como una referencia de variable de entorno como en el ejemplo.

La interpolación de $BB_KEY funciona, pero falla en silencio. Con la variable exportada verás Connected. Si abres una terminal nueva sin exportarla, la misma configuración mostrará Disconnected sin indicar un fallo de autenticación. Vale la pena añadir la línea de exportación a tu perfil de shell.

Gemini CLI sondea SSE y recibe un 405. Al observar los registros del servidor durante una conexión, la secuencia fue: POST initialize (200), POST notification (202), GET /api/mcp (405), POST tools/list (200). La petición GET corresponde al intento de la CLI de abrir un canal de Server-Sent Events en un servidor stateless. Falla con 405, la CLI continúa sin problemas y todo funciona correctamente. Si ejecutas tu propio servidor MCP, no te preocupes por ese 405.

Qué herramientas obtienes y cuánto cuestan

En la sesión aparecen nueve herramientas, el mismo conjunto disponible en la referencia de herramientas. Cuatro son gratuitas: list_models, get_account, get_result y list_generations. El resto se factura por generación desde el saldo de tu cuenta.

Las llamadas de video y de múltiples imágenes siempre cotizan primero. El agente recibe el precio exacto, no se cobra nada de antemano y la generación comienza solo tras confirmar ese monto. Los rechazos por filtros de seguridad y los fallos en upstream se reembolsan automáticamente, algo fundamental al procesar lotes de prompts en segundo plano.

Las recargas incluyen bonificaciones: 5% a partir de $50, 10% a partir de $100, y un código promocional activo suma un 10% adicional del depósito. Un depósito de $100 con código acredita $120.

Generar imágenes de Nano Banana en Gemini: ¿por qué tiene sentido?

Que Gemini CLI consulte un modelo gráfico de Gemini a través de un servidor externo puede parecer una ruta indirecta. Existe un camino directo: configurar una cuenta de facturación en Google Cloud, habilitar las API de modelos, gestionar credenciales y controlar cuotas por región. Es una opción válida si tu trabajo es diseñar infraestructura.

Este enfoque resuelve otra necesidad: un único token de acceso, saldo prepagado, sin cuentas de facturación en la nube, sin solicitudes de cuota ni dependencias regionales. Además obtienes los modelos de video Veo y Omni y síntesis de voz mediante la misma conexión, con cobro por generación en vez de costos por proyecto. Si tu prioridad es crear en lugar de administrar plataformas, suele ser la mejor alternativa.

A gran escala, el acceso directo a la nube resulta más económico. Pero nuestra opción permite arrancar en dos minutos y evita facturas sorpresa por servicios olvidados en la nube.

Si utilizas otros editores, el mismo servidor se integra con Claude Code, Cursor y Codex usando el mismo API key y su archivo de configuración correspondiente.

Caso de uso práctico: ilustraciones para documentación

Un caso de uso ideal: un repositorio con una carpeta docs/, doce páginas, y la necesidad de una cabecera para cada una con un estilo gráfico uniforme.

Prompt en la sesión:

Read every heading in docs/*.md. For each file, generate a 16:9 illustration matching the page topic, in this style: editorial illustration, pastel paper background, dark ink details, violet and amber accents, no text. Use nano-banana-pro. Save each as docs/img/.png and add the image reference under the page title.

El agente lee los archivos, invoca generate_image por página, sondea con get_result, descarga las imágenes y escribe la referencia en markdown. Doce imágenes a $0.11 suman $1.32, y todo se ejecuta mientras tomas un café. Todas las ilustraciones de este artículo se generaron mediante ese mismo flujo con Nano Banana Pro y una descripción de estilo compartida.

Dos recomendaciones antes de empezar: genera una primera imagen de prueba para validar el estilo (un error de descripción multiplicado por doce son $1.32 desperdiciados) y mantén desactivado --trust, ya que las confirmaciones por llamada previenen bucles accidentales del agente en herramientas de pago.

¿Funciona OAuth en lugar de una clave API?

Gemini CLI documenta soporte para OAuth 2.0 en servidores MCP remotos, con descubrimiento y el comando /mcp auth. Nuestro servidor funciona como un servidor de autorización OAuth 2.1 completo (registro dinámico de clientes, PKCE S256, descubrimiento RFC 9728), y clientes como Claude Code y claude.ai inician sesión de esa forma sin requerir una clave manual.

El flujo con API key está probado de extremo a extremo y funciona de forma estable. La ruta OAuth a través de Gemini CLI no la validamos en esta sesión en particular, por lo que conviene tratarla como factible pero sin garantía absoluta. Crear la clave toma diez segundos y no expira a menos que la revoques.

Preguntas frecuentes

¿Dónde se guarda el archivo de configuración?

En ~/.gemini/settings.json para el alcance de usuario, o en .gemini/settings.json para el alcance de proyecto. gemini mcp add --scope user escribe en el primero.

¿Por qué el servidor muestra Disabled?

La carpeta no está en la lista de confianza. Confirma la confianza de forma interactiva al iniciar o añade la ruta a ~/.gemini/trustedFolders.json con el valor TRUST_FOLDER. Los servidores de usuario también se bloquean en carpetas no confiables.

¿Puedo limitar qué herramientas ve el modelo?

Sí. Usa --include-tools y --exclude-tools en gemini mcp add, o define includeTools / excludeTools en la configuración. Las exclusiones tienen prioridad sobre las inclusiones, útil si quieres habilitar imágenes pero restringir video.

¿Funciona en un proyecto compartido con mi equipo?

Configura el servidor a nivel de proyecto y la clave mediante una variable de entorno, nunca en texto plano. Cada desarrollador ejecuta export BB_KEY=… con su propia clave y el repositorio permanece limpio.

¿Qué sucede si una generación falla?

Recibes un reembolso automático, incluidos los rechazos del filtro de contenido. Si un prompt queda al límite de las políticas, vale la pena reintentarlo: el análisis de seguridad evalúa los píxeles generados y un segundo intento produce una imagen distinta.

¿Prefieres una interfaz gráfica? El generador web permite usar los mismos modelos con el mismo saldo. En la CLI, tras conectar, prueba list_models: es gratuito, muestra los precios actuales y confirma que todo funciona antes de gastar tres centavos.