image-gen-mcp

Un servidor MCP que genera imágenes con los modelos nativos de imagen de Gemini de Google ("Nano Banana"), servido sobre Streamable HTTP.

Una única herramienta, generate_image. Sin estado en ninguna parte y sin autenticación propia: en producción funciona como backend detrás de mcp-oauth-proxy, desplegado por cloudrun-mcp-deployment.

DESIGN.md explica por qué se ha construido así; este archivo explica cómo ejecutarlo.

Inicio rápido (local, autenticación de token)

Configura un cliente para que apunte a http://127.0.0.1:8080/mcp con Authorization: Bearer $IMAGE_MCP_TOKEN. Para Claude Code:

uv sync
export GEMINI_API_KEY="…"                       # from Google AI Studio
export IMAGE_MCP_TOKEN="$(openssl rand -base64 32)"
uv run python -m image_gen_mcp

claude mcp add --transport http image-gen http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $IMAGE_MCP_TOKEN"

Related MCP server: Imagen MCP Server

La herramienta

generate_image(prompt, aspect_ratio="1:1", image_size="1K", model=None)

Las imágenes de hasta IMAGE_MCP_INLINE_MAX_BYTES (por defecto 1.5 MB) se devuelven en línea y se renderizan en el chat. Las más grandes se suben a Cloud Storage y se devuelven como una URL firmada. La salida estructurada siempre informa de las dimensiones reales en píxeles, el modelo utilizado y la ruta de entrega tomada.

Compatibilidad de modelos y resoluciones

Las combinaciones no admitidas se rechazan en el límite de la herramienta, en milisegundos, con un mensaje que indica lo que sí es compatible, en lugar de hacerlo tras una ida y vuelta de 30 segundos.

Configuración

Todo proviene del entorno. Consulta .env.example para la lista anotada; lo esencial:

El servidor prefiere no arrancar a funcionar mal configurado: la falta de clave de API y la ausencia total de frontera de autenticación (ni token estático ni modo proxy) son ambas errores de arranque.

Autenticación

Dos configuraciones posibles, y el servidor se niega a arrancar si no hay ninguna.

Detrás del proxy (producción). Establece IMAGE_MCP_TRUST_PROXY_HEADERS=1. El proxy autentica al usuario contra Google, aplica su lista permitida, elimina el encabezado Authorization del cliente y reenvía la identidad como X-Auth-Email / X-Auth-Subject / X-Auth-Scope. Este servidor lee esas cabeceras y no requiere token propio: una petición sin X-Auth-Email recibe un 401.

Confiar en las cabeceras es seguro solo porque nada más puede alcanzar el proceso: en el diseño multi-contenedor de Cloud Run, el backend no declara ningún puerto de ingreso, por lo que las únicas cosas que pueden abrir un socket hacia él son el proxy de la misma instancia y la sonda de arranque. Nunca habilites esto en un puerto enrutable.

ALLOWED_EMAILS es opcional aquí y acota la lista del proxy: resulta útil cuando el proxy admite a todo un dominio, pero la generación de imágenes debería suponer un coste solo para unas pocas personas. Si no se define, vale «todos los que el proxy haya admitido».

Token (local, Claude Code). Deja IMAGE_MCP_TRUST_PROXY_HEADERS sin definir y establece IMAGE_MCP_TOKEN. Los clientes envían Authorization: Bearer <token>; las cabeceras X-Auth-* se ignoran por completo, ya que sin el proxy son solo datos de petición no fiables.

El servidor no termina OAuth y no tiene endpoints /authorize, /token ni /register. Definir GOOGLE_OAUTH_CLIENT_ID o _SECRET es un error de arranque, no una operación silenciosa: esos valores pertenecen al proxy.

Construcción de la imagen

.github/workflows/build.yml ejecuta las pruebas, construye la imagen y la publica en GitHub Container Registry. No despliega — el despliegue lo gestiona un flujo de trabajo o repositorio separado.

Se publica como ghcr.io/ramzpat/image-gen-mcp. No hay nada que configurar: el flujo de trabajo se autentica con el GITHUB_TOKEN integrado.

Cómo consumirlo desde un flujo de despliegue

Despliega por resumen, no por etiqueta. Una caché de pull-through delante de una etiqueta mutable como :latest puede servir fácilmente una imagen antigua; un resumen de contenido no puede quedarse desactualizado. Cada ejecución imprime el resumen en el resumen del trabajo, y el flujo de trabajo se puede invocar si se quiere compilar y desplegar en una sola pipeline:

jobs:
  build:
    uses: ramzpat/image-gen-mcp/.github/workflows/build.yml@main
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploying ${{ needs.build.outputs.image }}@${{ needs.build.outputs.digest }}"

Desde un repositorio separado, resuelve el resumen de contenido en el momento del despliegue:

DIGEST=$(docker buildx imagetools inspect \
  ghcr.io/ramzpat/image-gen-mcp:latest --format '{{.Manifest.Digest}}')

El paquete GHCR es privado por defecto. Un trabajo de despliegue en otro repositorio necesita o bien un PAT con read:packages, o que el paquete esté configurado como público en los ajustes de paquetes de GitHub.

Despliegue

Lo despliega cloudrun-mcp-deployment (.github/workflows/deploy-image-gen-mcp.yml), que ejecuta esta imagen como contenedor backend de un servicio multi-contenedor de Cloud Run con mcp-oauth-proxy delante. Ese repositorio gestiona el proyecto GCP, la región, la lista permitida y los secretos; este solo publica la imagen.

Lo que ese despliegue define en este contenedor:

HOST=0.0.0.0 en lugar de loopback es un requisito, no una fuga: la sonda de arranque de Cloud Run funciona fuera del namespace de red del contenedor y no puede alcanzar un socket solo de loopback. Solo el contenedor que declara --port (el proxy) recibe tráfico entrante, por lo que el backend sigue sin poder accederse desde fuera de la instancia.

Cloud Storage para 2K/4K

gcloud storage buckets create gs://BUCKET --uniform-bucket-level-access
gcloud storage buckets update gs://BUCKET \
  --lifecycle-file=<(echo '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}')

# The runtime service account signs URLs through the IAM Credentials API,
# because it has no private key file. It needs this role *on itself*:
gcloud iam service-accounts add-iam-policy-binding RUNTIME_SA \
  --member="serviceAccount:RUNTIME_SA" --role=roles/iam.serviceAccountTokenCreator
gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member="serviceAccount:RUNTIME_SA" --role=roles/storage.objectAdmin

Omitir la vinculación serviceAccountTokenCreator es la forma más común de que las URL firmadas salgan rotas.

Tests

uv run pytest -q

57 tests: comprobaciones de arranque, resolución de identidad en ambos casos (cabeceras de proxy, token estático y cada uno ignorando la credencial del otro), validación y entrega de la herramienta, y pruebas de humo completas que manejan un cliente MCP real sobre HTTP real contra uvicorn — tanto en modo token como en la forma de producción con proxy.

Coste

Cada usuario de la lista permitida consume una única API key. Los controles, en orden de efectividad real: --max-instances, IMAGE_MCP_MAX_CONCURRENCY, una alerta de presupuesto de facturación de GCP y IMAGE_MCP_RATE_PER_HOUR. El límite de solicitudes se cuenta por instancia, por lo que su techo real es IMAGE_MCP_RATE_PER_HOUR × --max-instances.