Kleo MCP

npx add-mcp 'https://mcp.kleooai.com/mcp'

Servidor Kleo MCP

Kleo es un servidor remoto de Model Context Protocol que renderiza videos y Shorts de YouTube. Un usuario conecta una URL a Claude, ChatGPT, Grok, Claude Code, Cursor, VS Code, OpenCode o Gemini CLI, presiona un botón para entrar (sin correo, sin contraseña, sin código de invitación) y pide un video en lenguaje natural. El render se ejecuta en una máquina GPU alquilada solo para ese trabajo (Vast.ai) con el motor de diseño de movimiento Keou; cada toma es un clip generado comprado a kie.ai; el resultado llega como enlaces de descarga firmados (MP4, subtítulos .srt, miniatura) que duran 7 días.

El servidor se ejecuta enteramente en Cloudflare (Workers + KV + D1 + R2 + Workers AI + Cron), plan gratuito. Dirección de producción: https://mcp.kleooai.com/mcp (HTTP Streamable, OAuth 2.1; el Worker responde en https://kleo-mcp.plural-juice.workers.dev/mcp). El sitio público (../kleo-site) lee esa dirección desde su config.json.

Conectar

Dónde	Cómo
Claude (web/escritorio)	Configuración → Conectores → Añadir conector personalizado → https://mcp.kleooai.com/mcp
Claude Code	claude mcp add --transport http kleo https://mcp.kleooai.com/mcp
ChatGPT	Configuración → Conectores → Modo desarrollador → Crear → https://mcp.kleooai.com/mcp, OAuth
Cursor / VS Code / OpenCode / Gemini CLI	un servidor http llamado kleo con la misma URL
Registro MCP	com.kleooai/kleo (ver server.json)

Un botón te registra (sin correo, sin contraseña); 7 créditos llegan con la cuenta. Guías con capturas de pantalla: https://kleooai.com/connect/

Herramientas

Herramienta	Qué hace
kleo_adapt_prompt	Se llama primero. Lee la solicitud contra el intake de Kleo (tema, duración, formato, aspecto; audiencia, tono, qué debe aparecer), responde con las preguntas que la solicitud deja abiertas, y una vez que todo se conoce, entrega al asistente el método del productor para escribir el tratamiento.
kleo_list_templates	Las diez plantillas (formato, rango de duración, voces, costo en créditos) y los créditos restantes en la cuenta.
kleo_storyboard_guide	El formato de storyboard que Kleo renderiza (estilos, tipos de escena, beats, iconos, voces, reglas) con ejemplos, para que el asistente pueda escribir un storyboard original. Opcional: sin uno, Kleo planifica el video a partir del prompt.
kleo_create_video	Pone en cola un render desde una plantilla, un prompt y (opcionalmente) un storyboard. Devuelve job_id, eta_min y los créditos cobrados de una vez; no se cobra nada en caso de error.
kleo_wait_for_video	Espera (tanto como el cliente que llama lo permita: 45 s para ChatGPT/Grok, hasta 5 min para OpenCode) y devuelve los enlaces en cuanto el video está listo, para que el asistente mantenga su spinner y entregue por sí mismo.
kleo_get_job	Estado, pista actual, porcentaje y minutos restantes; sin job_id, los videos recientes de la cuenta.
kleo_get_result	Enlaces de descarga firmados para un trabajo terminado.
kleo_generate_thumbnail	Aún no habilitado en la beta (cada render ya incluye una miniatura): registra la solicitud y devuelve un aviso.
kleo_cancel_job	Cancela un trabajo en cola o en ejecución y reembolsa los créditos no utilizados.
kleo_account	Créditos restantes, el enlace de solo lectura a la página de la cuenta (/credits) y la "clave Kleo" que lleva la cuenta a otro navegador. El enlace es seguro para pegar en cualquier lugar; la clave es la cuenta.

Créditos (src/templates.ts): 1 crédito = 2 segundos de película, redondeado hacia arriba, mínimo 10 créditos; la película se hace para cuentas que compraron un paquete de créditos (€5 = 10 créditos, €15 = 35, €40 = 100, único pago, sin suscripción). El animatic (el mismo storyboard con la cámara moviéndose sobre fotogramas dibujados, sin clip generado, 15–60 s) cuesta 5 créditos y está abierto a todas las cuentas: los 7 créditos que vienen con una cuenta nueva pagan uno. tariffSentence() es la frase que cita cada página. Las cuentas son anónimas: sin correo y sin contraseña, solo un handle firmado con HMAC (src/accounts.ts) guardado en una cookie, que también funciona como la "clave Kleo" pegable. La tabla D1 invites sobrevive solo como un regalo opcional: un código escrito en el campo colapsado de la página de registro añade créditos además de los gratuitos, y un código desconocido nunca bloquea a nadie. Salida: 2160×3840 para 9:16, 1920×1080 para 16:9, 60 fps, H.264 + AAC. Un Short tarda unos 10–20 minutos incluyendo el arranque de la máquina; un video largo tarda proporcionalmente más, y el tiempo de espera que se le da a un render sigue la duración que se le cotizó (jobTimeoutMin), nunca un número fijo por debajo.

Cómo fluye un trabajo

client (Claude…) ──OAuth 2.1──▶ /mcp  (src/mcp.ts; login page in src/auth.ts)
                                │  D1: users, credits, gift codes, jobs, audit · KV: OAuth tokens · R2: rendered files
                                │  cron every minute (src/orchestrator.ts):
                                │    1. a storyboard for each queued job (Workers AI, src/storyboard.ts; validated by src/keou-contract.ts)
                                │    2. one Vast.ai instance per job (src/backends/vast.ts, image VAST_IMAGE)
                                │    3. watch running jobs, apply timeouts, purge expired files
                                ▼
                     Vast.ai instance → worker/kleo_worker.py (Keou engine) → uploads → POST /internal/jobs/:id/done → self-destroys
                     Free fallback: a GitHub Actions runner (.github/workflows/render-pool.yml) claims jobs that Vast could not start
                     (POST /internal/pool/claim with POOL_SECRET) and runs the same worker image.

Backends de render (RENDER_BACKEND): vast (producción: GPUs reales, cuesta dinero), mock (render simulado de un minuto con archivos de marcador de posición, gratuito; el servidor le dice a cada cliente que los renders son simulados), pool (solo runners externos), manual (un contenedor que inicias a mano; usado por test/worker-e2e.mjs).

Imagen del Worker

worker/Dockerfile.keou construye ghcr.io/tonnooooo/kleo-worker:keou (aproximadamente 11 GB: motor Keou, Chromium, Node, ffmpeg, voces Kokoro, faster-whisper). GitHub Actions (.github/workflows/worker-image.yml) la construye y la publica en cada push a main que toque worker/, o a mano desde la pestaña Actions. El paquete debe permanecer público en ghcr.io para que las máquinas de Vast.ai puedan extraerlo. Detalles: worker/README-keou.md.

Desarrollo local

npm install
npm run db:migrate:local
npm run dev                # http://localhost:8787 with .dev.vars: simulated renders, no GPU, bundled storyboard (STORYBOARD_FIXTURE=example)

Conecta Claude Code al servidor local: claude mcp add --transport http kleo-local http://localhost:8787/mcp, luego /mcp → Kleo → Autenticar y presiona el botón; no hay nada que escribir.

Pruebas

npm run test:smoke                                                  # starts its own wrangler dev on port 8799: OAuth, tools, queue, simulated render, signed download, cancel + refund
node --test test/keou-contract.test.mjs test/storyboard.test.mjs    # unit tests: storyboard validator and generator (offline, fake AI)
node --test test/accounts.test.mjs test/credits.test.mjs            # sign-in, signed handles, free credits, daily caps, credit lifecycle (offline, sqlite)
node test/worker-e2e.mjs                                            # real Keou render inside the container (podman, no GPU) against a local server in manual mode
node test/vast-e2e.mjs                                              # one real 20 s job on Vast.ai: costs a few cents, see the file header for the setup
npm run typecheck

Despliegue

Todo está aprovisionado: npm run deploy publica wrangler.jsonc (cada variable está explicada allí en un comentario de una línea). Configuración inicial, secretos y la guía paso a paso para el propietario (italiano): DEPLOY.md. Secretos: INTERNAL_SECRET, VAST_API_KEY (establecidos); POOL_SECRET (respaldo del pool); RESEND_API_KEY + NOTIFY_FROM (notificaciones por correo; no establecidos, por lo que notify_email actualmente es un no-op); TURNSTILE_SECRET (no establecido, por lo que la verificación de bots en la página de registro se omite). INTERNAL_SECRET nunca debe rotarse: firma tanto los handles de cuenta como los enlaces de descarga, por lo que un nuevo valor desconecta a cada usuario de sus créditos.

Para apagar las GPUs para una demo gratuita, establece RENDER_BACKEND a mock en wrangler.jsonc y despliega. Para detener el gasto ahora mismo, sin desplegar: POST /internal/admin/pause con Authorization: Bearer <INTERNAL_SECRET> (/internal/admin/resume para comenzar de nuevo). Ver sección 5 de DEPLOY.md.

Barreras de seguridad

Los créditos se debitan cuando un trabajo se pone en cola y se reembolsan en caso de fallo o cancelación; como máximo MAX_JOBS_PER_USER trabajos abiertos por cuenta y MAX_CONCURRENT_GPUS instancias en total; cada trabajo tiene un JOB_TIMEOUT_MIN duro después del cual la instancia se destruye, y una máquina que permanece en silencio durante START_TIMEOUT_MIN después del alquiler se destruye y el trabajo se vuelve a poner en cola; el worker lleva su propio watchdog y destruye su instancia con el CONTAINER_API_KEY restringido de Vast; después de una respuesta de "sin crédito / sin oferta", Vast se deja solo durante VAST_RETRY_MIN; los enlaces de descarga están firmados con HMAC y expiran con los archivos; un filtro de prompts bloquea contenido prohibido antes de gastar cualquier dinero en GPU.

Por encima de todo eso está DAILY_GPU_BUDGET_USD: antes de alquilar cualquier cosa, el orquestador suma lo que cuestan los alquileres de hoy — terminados, fallidos y cancelados por igual, ya que cost_usd se escribe cada vez que una máquina se derriba — a lo que las máquinas de pago que se ejecutan ahora mismo ya han comprometido (cada una con un precio de VAST_MAX_DPH por su propio tiempo de espera; los trabajos del pool gratuito no comprometen nada) y, por encima del límite, pausa los alquileres durante una hora mientras los trabajos mantienen su lugar en la cola. La cifra sigue siendo una estimación: el tope de precio es un límite superior y el número real es el saldo de Vast.ai. Las cuentas nuevas tienen un tope por día (MAX_NEW_USERS_PER_DAY) y por dirección por día (MAX_NEW_USERS_PER_IP_DAY, sobre un hash de la dirección), trabajos por cuenta por día (MAX_JOBS_PER_DAY, contando solo los que no fueron reembolsados), e intentos de registro por dirección por minuto (el enlace de límite de velocidad SIGNUP_LIMIT, con clave en un hash de la dirección, nunca la dirección misma). Cada límite se ejecuta dentro del Worker y solo en /authorize: nunca frente a /mcp, donde un 403 o 429 rompe los conectores antes de que la aplicación vea la solicitud.

Documentación

• DEPLOY.md — estado actual, puesta en marcha, operaciones diarias (italiano)
• docs/MCP-GUIDA.md — qué es MCP, cómo se conecta cada cliente, las siete herramientas (italiano)
• docs/ARCHITETTURA.md — el análisis de viabilidad original y la arquitectura (italiano)