Kleo MCP

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

Servidor Kleo MCP

Kleo é um servidor remoto de Model Context Protocol que renderiza vídeos e Shorts do YouTube. Um usuário conecta uma URL ao Claude, ChatGPT, Grok, Claude Code, Cursor, VS Code, OpenCode ou Gemini CLI, pressiona um botão para entrar (sem e-mail, sem senha, sem código de convite) e pede um vídeo em linguagem natural. A renderização roda em uma máquina GPU alugada apenas para esse trabalho (Vast.ai) com o motor de motion design Keou, cada cena um clipe gerado comprado da kie.ai; o resultado volta como links de download assinados (MP4, legendas .srt, miniatura) que duram 7 dias.

O servidor roda inteiramente na Cloudflare (Workers + KV + D1 + R2 + Workers AI + Cron), plano gratuito. Endereço de produção: https://mcp.kleooai.com/mcp (HTTP Streamable, OAuth 2.1; o próprio Worker responde em https://kleo-mcp.plural-juice.workers.dev/mcp). O site público (../kleo-site) lê esse endereço do seu config.json.

Conectar

Onde	Como
Claude (web/desktop)	Configurações → Conectores → Adicionar conector personalizado → https://mcp.kleooai.com/mcp
Claude Code	claude mcp add --transport http kleo https://mcp.kleooai.com/mcp
ChatGPT	Configurações → Conectores → Modo desenvolvedor → Criar → https://mcp.kleooai.com/mcp, OAuth
Cursor / VS Code / OpenCode / Gemini CLI	um servidor http chamado kleo com a mesma URL
MCP Registry	com.kleooai/kleo (veja server.json)

Um botão faz seu login (sem e-mail, sem senha); 7 créditos chegam junto com a conta. Guias com capturas de tela: https://kleooai.com/connect/

Ferramentas

Ferramenta	O que faz
kleo_adapt_prompt	Chamada primeiro. Lê a solicitação contra o intake da Kleo (assunto, duração, formato, visual; público, tom, o que deve aparecer), responde com as perguntas que a solicitação deixa em aberto e, quando tudo está definido, entrega ao assistente o método do produtor para escrever o tratamento.
kleo_list_templates	Os dez modelos (formato, faixa de duração, vozes, custo em créditos) e os créditos restantes na conta.
kleo_storyboard_guide	O formato de storyboard que a Kleo renderiza (estilos, tipos de cena, batidas, ícones, vozes, regras) com exemplos, para o assistente escrever um storyboard original. Opcional: sem um, a Kleo planeja o vídeo a partir do prompt.
kleo_create_video	Enfileira uma renderização a partir de um modelo, um prompt e (opcionalmente) um storyboard. Retorna job_id, eta_min e os créditos cobrados de uma vez; nada é cobrado em caso de erro.
kleo_wait_for_video	Aguarda (pelo tempo que o cliente chamador permitir: 45 s para ChatGPT/Grok, até 5 min para OpenCode) e retorna os links assim que o vídeo estiver pronto, para o assistente manter o spinner e entregar por conta própria.
kleo_get_job	Estado, faixa atual, percentual e minutos restantes; sem job_id, os vídeos recentes da conta.
kleo_get_result	Links de download assinados para um trabalho concluído.
kleo_generate_thumbnail	Ainda não habilitado na versão beta (toda renderização já inclui uma miniatura): registra a solicitação e retorna um aviso.
kleo_cancel_job	Cancela um trabalho enfileirado ou em execução e reembolsa os créditos não utilizados.
kleo_account	Créditos restantes, o link somente leitura para a página da conta (/credits) e a "chave Kleo" que leva a conta para outro navegador. O link é seguro para colar em qualquer lugar; a chave é a conta.

Créditos (src/templates.ts): 1 crédito = 2 segundos de filme, arredondado para cima, mínimo de 10 créditos; o filme é feito para contas que compraram um pacote de créditos (€5 = 10 créditos, €15 = 35, €40 = 100, pagamento único, sem assinatura). O animatic (o mesmo storyboard com a câmera se movendo sobre quadros desenhados, sem clipe gerado, 15–60 s) custa 5 créditos e está aberto a todas as contas: os 7 créditos que acompanham uma conta nova pagam um. tariffSentence() é a frase que toda página cita. As contas são anônimas: sem e-mail e sem senha, apenas um identificador assinado com HMAC (src/accounts.ts) mantido em um cookie, que também serve como a "chave Kleo" colável. A tabela D1 invites sobrevive apenas como um presente opcional: um código digitado no campo recolhido da página de login adiciona créditos além dos gratuitos, e um código desconhecido nunca bloqueia ninguém. Saída: 2160×3840 para 9:16, 1920×1080 para 16:9, 60 fps, H.264 + AAC. Um Short leva cerca de 10–20 minutos incluindo a inicialização da máquina; um vídeo longo leva proporcionalmente mais tempo, e o timeout dado a uma renderização segue a duração que foi cotada (jobTimeoutMin), nunca um número fixo abaixo dela.

Como um trabalho flui

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 renderização (RENDER_BACKEND): vast (produção: GPUs reais, custa dinheiro), mock (renderização simulada de um minuto com arquivos de espaço reservado, gratuita; o servidor informa a todo cliente que as renderizações são simuladas), pool (apenas executores externos), manual (um contêiner que você inicia manualmente; usado por test/worker-e2e.mjs).

Imagem do Worker

worker/Dockerfile.keou constrói ghcr.io/tonnooooo/kleo-worker:keou (cerca de 11 GB: motor Keou, Chromium, Node, ffmpeg, vozes Kokoro, faster-whisper). GitHub Actions (.github/workflows/worker-image.yml) constrói e envia a cada push para main que toque em worker/, ou manualmente pela aba Actions. O pacote deve permanecer público no ghcr.io para que as máquinas Vast.ai possam puxá-lo. Detalhes: worker/README-keou.md.

Desenvolvimento 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)

Conecte o Claude Code ao servidor local: claude mcp add --transport http kleo-local http://localhost:8787/mcp, depois /mcp → Kleo → Autenticar e pressione o botão; não há nada para digitar.

Testes

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

Implantação

Tudo está provisionado: npm run deploy publica wrangler.jsonc (cada variável é explicada lá em um comentário de uma linha). Configuração inicial, segredos e o guia passo a passo para o proprietário (italiano): DEPLOY.md. Segredos: INTERNAL_SECRET, VAST_API_KEY (definidos); POOL_SECRET (fallback do pool); RESEND_API_KEY + NOTIFY_FROM (notificações por e-mail; não definidos, então notify_email é atualmente um no-op); TURNSTILE_SECRET (não definido, então a verificação de bot na página de login é ignorada). INTERNAL_SECRET nunca deve ser rotacionado: ele assina os identificadores de conta e também os links de download, então um novo valor desvincula cada usuário de seus créditos.

Para desligar as GPUs para uma demonstração gratuita, defina RENDER_BACKEND como mock em wrangler.jsonc e implante. Para interromper os gastos agora, sem implantar: POST /internal/admin/pause com Authorization: Bearer <INTERNAL_SECRET> (/internal/admin/resume para reiniciar). Veja a seção 5 do DEPLOY.md.

Salvaguardas de segurança

Os créditos são debitados quando um trabalho é enfileirado e reembolsados em caso de falha ou cancelamento; no máximo MAX_JOBS_PER_USER trabalhos abertos por conta e MAX_CONCURRENT_GPUS instâncias no total; todo trabalho tem um JOB_TIMEOUT_MIN rígido após o qual a instância é destruída, e uma máquina que permanece silenciosa por START_TIMEOUT_MIN após o aluguel é destruída e o trabalho é reenfileirado; o worker carrega seu próprio watchdog e destrói sua instância com o CONTAINER_API_KEY restrito da Vast; após uma resposta "sem crédito / sem oferta", a Vast é deixada em paz por VAST_RETRY_MIN; os links de download são assinados com HMAC e expiram junto com os arquivos; um filtro de prompt bloqueia conteúdo proibido antes que qualquer dinheiro de GPU seja gasto.

Acima de tudo isso está DAILY_GPU_BUDGET_USD: antes de alugar qualquer coisa, o orquestrador soma o que os aluguéis de hoje custam — concluídos, falhos e cancelados igualmente, já que cost_usd é escrito toda vez que uma máquina é derrubada — ao que as máquinas pagas em execução agora já comprometeram (cada uma precificada em VAST_MAX_DPH para seu próprio timeout; trabalhos do pool gratuito não comprometem nada) e, acima do teto, pausa os aluguéis por uma hora enquanto os trabalhos mantêm seu lugar na fila. O valor ainda é uma estimativa: o teto de preço é um limite superior e o número real é o saldo da Vast.ai. Novas contas são limitadas por dia (MAX_NEW_USERS_PER_DAY) e por endereço por dia (MAX_NEW_USERS_PER_IP_DAY, em um hash do endereço), trabalhos por conta por dia (MAX_JOBS_PER_DAY, contando apenas os que não foram reembolsados) e tentativas de login por endereço por minuto (o binding de rate-limit SIGNUP_LIMIT, com chave em um hash do endereço, nunca o endereço em si). Todo limite roda dentro do Worker e apenas em /authorize: nunca na frente de /mcp, onde um 403 ou 429 quebra os conectores antes que o aplicativo veja a solicitação.

Documentação

• DEPLOY.md — status atual, entrada em produção, operações do dia a dia (italiano)
• docs/MCP-GUIDA.md — o que é MCP, como cada cliente se conecta, as sete ferramentas (italiano)
• docs/ARCHITETTURA.md — a análise de viabilidade original e a arquitetura (italiano)