Gemini Image MCP

Un servidor MCP para generar y editar imágenes con los modelos de imagen Gemini de Google (Nano Banana, Nano Banana 2, Nano Banana Pro). Expone una herramienta, generate_image, que herramientas de IA como Claude, Codex y Cline pueden llamar usando tu propia clave API.

Qué hace

• generate_image maneja texto a imagen, además de edición y composición cuando le pasas imágenes de referencia (rutas de archivo locales o base64).

• Cada parámetro de generación se expone por llamada: temperature (1), topP (0.95), topK, maxOutputTokens (65536 para flash/lite, 32768 para pro), seed, stopSequences, presencePenalty, frequencyPenalty, systemInstruction, thinkingLevel (minimal/high), thinkingBudget, enableGoogleSearch (por defecto true), imageSize (512/1K/2K/4K), aspectRatio ("auto" por defecto + relaciones estándar), personGeneration.

• Incluye un bloque instructions y descripciones por parámetro, para que los clientes MCP sepan cómo usar la herramienta sin necesidad de indicaciones adicionales.

• Guarda las imágenes en disco y devuelve las rutas de archivo. Sin base64 en la respuesta, así que una imagen 4K no consumirá la ventana de contexto del cliente.

• Los errores llegan con pistas (clave incorrecta, límite de velocidad, bloqueo de seguridad, modelo desconocido) en lugar de un volcado de API sin procesar.

• Transporte stdio, la configuración habitual para servidores MCP locales.

Requisitos

• Bun 1.0+

• Una clave API de Gemini desde https://aistudio.google.com/apikey

Instalar

bun install

Configuración

Tres variables de entorno, normalmente establecidas en la configuración del cliente MCP:

Modelos que puedes elegir:

Los modelos también se pueden especificar con el prefijo models/ (por ejemplo, models/gemini-3.1-flash-image).

Configuración del cliente

Claude Desktop

Añade esto a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

Desde npm (bunx/npx)

Una vez que el paquete esté publicado, apunta tu cliente a bunx en su lugar:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

Parámetros de generate_image

Solo prompt es obligatorio. Todo lo demás se predetermina a algo sensato para la generación de imágenes.

La herramienta devuelve un resumen de texto con las rutas de archivo guardadas, el modelo, la configuración efectiva y el uso de tokens. Nunca devuelve datos de imagen en línea; abre el archivo para ver el resultado.

Cosas que puedes pedirle a tu IA

• "Genera una imagen heroica 16:9 de una calle lluviosa de Tokio por la noche, con iluminación neón cinematográfica."

• "Edita /tmp/product.png: ponlo sobre una mesa de mármol con luz suave de la mañana" (esto usa referenceImages).

• "Genera un póster 4K con el título exacto 'LAUNCH DAY' usando gemini-3-pro-image."

Desarrollo

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

Solución de problemas

• "Falta la clave API de Gemini": pon GEMINI_API_KEY en el bloque env de la configuración MCP del cliente. Configurarla en tu shell no es suficiente para aplicaciones GUI como Claude Desktop, ya que no leen tu entorno de shell.

• Bloqueos de seguridad: reformula la prompt. Si hay personas involucradas, comprueba personGeneration.

• 429 / cuota excedida: espera y vuelve a intentarlo, o quédate con gemini-3.1-flash-image, que tiene la cuota más alta.

• Registros: el servidor escribe registros solo en stderr. stdout transporta el protocolo MCP, así que no añadas console.log en ningún lugar.

Autor

Thomi Jasir dev@venobi.com

Licencia

MIT