Kleo

Kleo MCP 服务

Kleo 是一个远程 Model Context Protocol 服务，可渲染 YouTube 视频和 Shorts。用户将一个 URL 连接到 Claude、ChatGPT、Grok、Claude Code、Cursor、VS Code、OpenCode 或 Gemini CLI，按下一个按钮即可进入（无需邮箱、密码或邀请码），然后用通俗语言描述想要的视频。渲染任务会在仅为此任务租用的 GPU 机器（Vast.ai）上运行，并使用 Keou 动态设计引擎；完成后会返回带签名的下载链接（MP4、.srt 字幕、缩略图），有效期为 7 天。

服务完全运行在 Cloudflare 上（Workers + KV + D1 + R2 + Workers AI + Cron），使用免费套餐。生产环境地址：https://mcp.kleooai.com/mcp（Streamable HTTP、OAuth 2.1；Worker 本身的响应地址为 https://kleo-mcp.plural-juice.workers.dev/mcp）。公开网站（../kleo-site）从其 config.json 中读取该地址。

模型

影片部分	模型
动态画面（影片中的每个镜头）	ByteDance Seedance 2.5，根据镜头自身的画面进行图生视频
画面和角色设定图（用户提供照片时使用其照片）	Google Nano Banana Pro
画面检查	视觉模型会在拍摄前将每张画面与用户的要求进行比较
音乐（按需提供）	Suno
旁白	Kokoro 语音，支持英语或意大利语
成片	4K 60 fps；可选在渲染 GPU 上进行 AI 升频（Real-ESRGAN + RIFE）

连接

平台	方法
Claude（网页/桌面）	Settings → Connectors → Add custom connector → https://mcp.kleooai.com/mcp
Claude Code	claude mcp add --transport http kleo https://mcp.kleooai.com/mcp
ChatGPT	Settings → Connectors → Developer mode → Create → https://mcp.kleooai.com/mcp，OAuth
Cursor / VS Code / OpenCode / Gemini CLI	使用同一 URL，添加名为 kleo 的 http 服务
MCP Registry	com.kleooai/kleo（参见 server.json）

按下一个按钮即可登录（无需邮箱或密码）；账户会获得 7 个积分。附截图的指南：https://kleooai.com/connect/

工具

工具	功能
kleo_adapt_prompt	首先调用。根据 Kleo 的需求收集表（主题、长度、格式、风格；受众、语气、必须包含的内容）检查请求，提出请求中尚未明确的问题，并在所有信息齐备后将制作方编写影片方案的方法交给助手。
kleo_list_templates	十种模板（格式、长度范围、配音、积分费用）以及账户剩余积分。
kleo_storyboard_guide	Kleo 渲染所用的分镜格式（风格、场景类型、节拍、图标、配音、规则）及示例，供助手编写原创分镜。可选：如果不提供，Kleo 会根据提示词规划视频。
kleo_create_video	根据模板、提示词和（可选的）分镜将渲染任务加入队列。会立即返回 job_id、eta_min 和扣除的积分；出错时不会扣除积分。
kleo_wait_for_video	等待视频就绪（时长不超过调用客户端允许的范围：ChatGPT/Grok 为 45 s，OpenCode 最长为 5 min），并在视频就绪后立即返回链接，让助手继续显示加载动画并自行交付视频。
kleo_get_job	返回状态、当前进度、百分比和剩余分钟数；不提供 job_id 时，返回账户最近的视频。
kleo_get_result	返回已完成任务的签名下载链接。
kleo_generate_thumbnail	Beta 版尚未启用（每次渲染都会附带缩略图）：记录请求并返回通知。
kleo_cancel_job	取消排队中或正在运行的任务，并退还未使用的积分。
kleo_account	返回剩余积分和账户页面的只读链接（/credits）。该链接可安全地粘贴到任何地方。用于将账户带到其他浏览器的“Kleo key”就是账户本身，因此绝不会通过 MCP 返回：用户可以在 Kleo Studio 中查看（账户 → Kleo key），也可以在连接时使用的浏览器中访问 /credits 查看。

积分（src/templates.ts）：1 积分 = 2 秒影片时长，向上取整，最低 10 积分；影片面向购买积分包的账户制作（€5 = 10 积分，€15 = 35 积分，€40 = 100 积分，一次性购买，不订阅）。Animatic（同一份分镜，镜头在绘制帧上移动，不生成片段，时长 15–60 s）收费 5 积分，对所有账户开放：新账户赠送的 7 积分足以制作一部。tariffSentence() 是每个页面引用的句子。账户为匿名账户：无需电子邮件和密码，只使用保存在 cookie 中的 HMAC 签名句柄（src/accounts.ts），它也可作为便于粘贴的“Kleo key”。D1 表 invites 仅作为可选赠礼保留：在登录页面展开的字段中输入代码，即可在免费积分之外获得额外积分；未知代码绝不会阻止任何人使用服务。输出：9:16 为 2160×3840，16:9 为 1920×1080，60 fps，H.264 + AAC。一部 Short 大约需要 10–20 分钟（包括机器启动时间）；长视频所需时间按比例增加，渲染任务的超时时间会根据报价时长设定（jobTimeoutMin），绝不会低于该时长并采用固定值。

任务流程

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.

渲染后端（RENDER_BACKEND）：vast（生产环境：使用真实 GPU，需付费）、mock（模拟一分钟渲染并使用占位文件，免费；服务器会告知每个客户端渲染为模拟结果）、pool（仅使用外部运行器）、manual（手动启动的容器；供 test/worker-e2e.mjs 使用）。

Worker 镜像

worker/Dockerfile.keou 构建 ghcr.io/tonnooooo/kleo-worker:keou（约 11 GB：Keou 引擎、Chromium、Node、ffmpeg、Kokoro 配音、faster-whisper）。GitHub Actions（.github/workflows/worker-image.yml）会在每次向 main 推送涉及 worker/ 的更改时自动构建并推送该镜像，也可以在 Actions 选项卡中手动触发。该软件包必须在 ghcr.io 上保持公开，以便 Vast.ai 机器拉取。详情：worker/README-keou.md。

本地开发

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)

将 Claude Code 连接到本地服务：claude mcp add --transport http kleo-local http://localhost:8787/mcp，然后选择 /mcp → Kleo → Authenticate 并按下按钮；无需输入任何内容。

测试

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

部署

所有内容均已配置：npm run deploy 会发布 wrangler.jsonc（其中每个变量都有一行注释说明）。首次设置、密钥以及面向所有者的分步指南（意大利语）：DEPLOY.md。密钥：INTERNAL_SECRET、VAST_API_KEY（已设置）；POOL_SECRET（资源池备用项）；RESEND_API_KEY + NOTIFY_FROM（邮件通知；尚未设置，因此 notify_email 目前不起作用）；TURNSTILE_SECRET（尚未设置，因此登录页面会跳过机器人检查）。切勿轮换 INTERNAL_SECRET：它既用于签署账户句柄，也用于签署下载链接，因此更换后所有用户都会与其积分脱离关联。

如要关闭 GPU，运行免费演示，请在 wrangler.jsonc 中将 RENDER_BACKEND 设为 mock，然后部署。如要立即停止开支且无需部署：使用 Authorization: Bearer <INTERNAL_SECRET> 调用 POST /internal/admin/pause（调用 /internal/admin/resume 可重新启动）。参见 DEPLOY.md 第 5 节。

安全措施

任务进入队列时会扣除积分，失败或取消时会退还；每个账户最多有 MAX_JOBS_PER_USER 个未完成任务，总计最多运行 MAX_CONCURRENT_GPUS 个实例；每个任务都有硬性超时 JOB_TIMEOUT_MIN，超时后实例会被销毁；机器租用后若在 START_TIMEOUT_MIN 时间内一直无响应，也会被销毁并重新将任务加入队列；Worker 自带看门狗，并使用 Vast 受限的 CONTAINER_API_KEY 销毁其实例；Vast 返回“无积分／无报价”后，会等待 VAST_RETRY_MIN 再尝试；下载链接经过 HMAC 签名，并会随文件一起过期；提示词过滤器会在产生任何 GPU 费用之前拦截禁止内容。

在上述限制之上，还有 DAILY_GPU_BUDGET_USD：租用任何机器之前，编排器会将今日租用费用（包括已完成、失败和取消的任务，因为每次拆除机器时都会写入 cost_usd）与当前运行的付费机器已产生的承诺费用相加（每台机器均按其自身超时时长，以 VAST_MAX_DPH 计价；免费资源池任务不计入承诺费用）。超出上限时，会暂停租用一小时，同时让任务保留在队列中的原有位置。该数值仍是估算值：价格上限只是一个上界，实际金额以 Vast.ai 余额为准。新账户每天都有数量上限（MAX_NEW_USERS_PER_DAY），每个地址每天也有数量上限（MAX_NEW_USERS_PER_IP_DAY，基于地址哈希）；每个账户每天的任务数有限（MAX_JOBS_PER_DAY，仅统计未退款的任务）；每个地址每分钟的登录尝试次数也有限（SIGNUP_LIMIT 速率限制绑定项，以地址哈希为键，绝不会使用地址本身）。所有限制均在 Worker 内运行，且仅针对 /authorize：绝不会设置在 /mcp 前，因为 403 或 429 会在应用收到请求之前破坏连接器。

文档

• DEPLOY.md — 当前状态、上线和日常运维（意大利语）
• docs/MCP-GUIDA.md — MCP 的介绍、各客户端的连接方式以及七个工具（意大利语）
• docs/ARCHITETTURA.md — 原始可行性分析和架构（意大利语）