GoogleFlow_MCP

Servidor MCP para crear videos e imágenes con los modelos de Google Flow (Veo 3.1 y Nano Banana) desde Claude Code y Codex, con instrucciones en lenguaje natural.

"Hazme un video vertical de 8 s de una taza de café humeante en una cocina al amanecer, cámara lenta, con sonido de lluvia."

El agente (Claude o Codex) convierte tu petición en un prompt cinematográfico, llama a Veo, espera el render y te deja el .mp4 en tu disco.

Cómo funciona

Claude Code / Codex  ──MCP (stdio)──▶  googleflow-mcp  ──Gemini API / Vertex AI──▶  Veo 3.1 · Nano Banana
                                              │
                                              └──▶ ./flow-output/{videos,images}/ + manifest.json

Importante: flow.google.com no tiene una API pública. Este servidor usa la API oficial de Gemini (o Vertex AI), que da acceso a los mismos modelos que usa Flow. Consecuencias:

• Los clips no aparecen en tu proyecto de Flow; se guardan en local (FLOW_OUTPUT_DIR). Puedes subirlos a Flow como "ingredients" si quieres seguir editando allí.

• Se cobra por uso a tu API key de Gemini / proyecto de Google Cloud, no con los créditos de tu suscripción de Google AI.

• No hace scraping ni automatiza el navegador, así que no rompe cuando Google cambia la interfaz de Flow ni viola sus términos.

Related MCP server: CapCut & Google Flow MCP

Herramientas

También incluye el prompt MCP flow_director: le das una idea y arma un guion de tomas y las renderiza paso a paso.

Las imágenes generadas reciben un id (img_…) que puedes pasar directamente como startImage, endImage o referenceImages para mantener la consistencia de personajes.

Requisitos

• Node.js 20 o superior

• Una API key de Gemini: https://aistudio.google.com/apikey (Veo necesita la facturación activada en el proyecto)

  • Alternativa: Vertex AI con gcloud auth application-default login

Instalación

PowerShell (Windows)

git clone https://github.com/marvicqui/GoogleFlow_MCP.git C:\src\GoogleFlow_MCP
cd C:\src\GoogleFlow_MCP
npm install      # también compila (script "prepare")

bash (macOS / Linux)

git clone https://github.com/marvicqui/GoogleFlow_MCP.git ~/src/GoogleFlow_MCP
cd ~/src/GoogleFlow_MCP
npm install

Conectar con Claude Code

# PowerShell
claude mcp add googleflow --scope user `
  -e GEMINI_API_KEY=$env:GEMINI_API_KEY `
  -e FLOW_OUTPUT_DIR="$HOME\Videos\flow" `
  -- node C:\src\GoogleFlow_MCP\dist\index.js

# bash
claude mcp add googleflow --scope user \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -e FLOW_OUTPUT_DIR="$HOME/Videos/flow" \
  -- node ~/src/GoogleFlow_MCP/dist/index.js

Comprueba con claude mcp list o /mcp dentro de Claude Code. Para compartirlo con un equipo, usa un .mcp.json en el repo (ver examples/claude-mcp.json).

Si un render largo se corta por tiempo, sube el timeout de herramientas MCP antes de abrir Claude Code: $env:MCP_TOOL_TIMEOUT=600000 (PowerShell) o export MCP_TOOL_TIMEOUT=600000 (bash). Otra opción es pedir wait: false y luego usar flow_check_operation.

Conectar con Codex

codex mcp add googleflow --env GEMINI_API_KEY=$env:GEMINI_API_KEY -- node C:\src\GoogleFlow_MCP\dist\index.js

Luego, en ~/.codex/config.toml, sube el timeout (un video tarda de 1 a 6 minutos y Codex corta a los 60 s por defecto):

[mcp_servers.googleflow]
command = "node"
args = ["C:\\src\\GoogleFlow_MCP\\dist\\index.js"]
tool_timeout_sec = 600

[mcp_servers.googleflow.env]
GEMINI_API_KEY = "tu-api-key"

Ejemplo completo en examples/codex-config.toml.

Variables de entorno

Google renombra los modelos a menudo (sobre todo los -preview). Si uno deja de existir, pide "lista los modelos de Flow disponibles" (flow_list_models) y ajusta la variable.

Ejemplos de instrucciones

• "Genera un video 16:9 de 8 segundos: dron sobrevolando un bosque de niebla al amanecer, estilo documental, con ambiente de pájaros."

• "Crea una imagen de mi personaje: una astronauta de 30 años con traje naranja, estilo Pixar. Luego haz un video donde ella camina por Marte usando esa imagen como referencia."

• "Usa C:\fotos\producto.png como primer fotograma y haz un giro de 360° del producto sobre fondo blanco, versión rápida."

• "Extiende el último video: la cámara se aleja y se ve la ciudad."

• "/mcp__googleflow__flow_director un anuncio de 30 segundos para una cafetería, formato 9:16"

Desarrollo

npm run dev       # tsc --watch
npm run inspect   # abre MCP Inspector para probar las herramientas

Estructura:

src/
  index.ts    # definición del servidor MCP, herramientas y prompt
  flow.ts     # cliente de Veo / Nano Banana (SDK @google/genai)
  store.ts    # manifest local de assets y operaciones pendientes
  config.ts   # variables de entorno

Limitaciones

• No lee ni escribe en tus proyectos de flow.google.com (no hay API pública para eso).

• flow_extend_video solo funciona con videos generados por este servidor; en la Gemini API el archivo remoto caduca a los ~2 días y la extensión es a 720p.

• Disponibilidad de funciones (4K, audio, imágenes de referencia, último fotograma) depende del modelo y de la región; si la API rechaza un parámetro, el error se devuelve al agente tal cual.

• Con la Gemini API, generateAudio y seed no existen: el servidor los ignora y lo indica en ignored. Veo 3.x genera audio siempre; describe los sonidos en el prompt.

• Veo no tiene capa gratuita en la Gemini API. Sin facturación activa verás 429 RESOURCE_EXHAUSTED aunque no hayas generado nada. Actívala en https://aistudio.google.com/apikey ("Set up billing") y revisa el consumo en https://aistudio.google.com/usage.

• Los videos de Veo llevan marca de agua SynthID.

Licencia

MIT