hyperframes-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hyperframes-mcp Render the intro composition in project launch to mp4."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hyperframes-mcp
Self-hosted MCP server that exposes the HyperFrames
CLI as agent tools. Runs on our own infra — agents connect to our endpoint,
not HeyGen's hosted connector (mcp.heygen.com) nor the browser-only WebMCP
surface of the Studio.
Tools
Tool | What it does |
| Lists HyperFrames projects in the workspace |
| Lists a project's compositions (JSON) |
| Runs the HyperFrames linter (a11y/layout/motion) |
| Renders a project/composition → mp4/webm/mov/gif/png-sequence |
| Captures PNG frames for visual QA |
| Scaffolds a new project from an example |
| Status + log of a render/snapshot job |
| Recent jobs and queue state |
| Blocks until a job finishes (or times out) |
| Cancels a queued or running job |
Rendering runs inside the container (chrome-headless-shell + ffmpeg bundled), so no external accounts or credits are needed.
Heavy ops are queued
render_video and snapshot_frames enqueue the work and return a job_id
immediately — a render takes minutes and must not hold the HTTP request open.
Follow it with get_job / wait_job / list_jobs / cancel_job, or pass
wait: true for short clips. Jobs are persisted to disk (HF_JOBS_DIR) so their
status survives restarts; render concurrency is capped by HF_JOB_CONCURRENCY.
Related MCP server: video-agent-mcp
Transports
HTTP (hosted):
MCP_TRANSPORT=http, served atPOST /mcp(Streamable HTTP, stateless). Rendered files are downloadable atGET /files/<path-relative-to-workspace>.stdio (local):
MCP_TRANSPORT=stdio— for Claude Code / Cursor / Codex.
Hosted (this deployment)
Live: https://hyperframes-mcp.lab.whitelabel.lat
{
"mcpServers": {
"hyperframes": {
"type": "http",
"url": "https://hyperframes-mcp.lab.whitelabel.lat/mcp"
}
}
}If MCP_AUTH_TOKEN is set, add "headers": { "Authorization": "Bearer <token>" }.
Local (stdio)
{
"mcpServers": {
"hyperframes": {
"command": "docker",
"args": ["run","-i","--rm","-e","MCP_TRANSPORT=stdio","hyperframes-mcp:latest"]
}
}
}Endpoints
POST /mcp— MCP (Streamable HTTP)GET /health— liveness (public; includes queue state)GET /jobs— list jobs (queue state + recent)GET /jobs/<id>— single job status/logPOST /jobs/<id>/cancel— cancel a jobGET /files/<path>— download rendered artifactsGET /— tool index
Env
Var | Default | Meaning |
|
|
|
|
| HTTP port |
| (empty) | If set, require |
|
| Where projects live |
|
| Where job records are persisted |
|
| Max renders/snapshots running at once |
|
| Log lines kept per job |
|
| Cap for |
|
| Upstream checkout / CLI entry |
|
| Render timeout (30 min) |
Notes / roadmap
Rendering is CPU/RAM heavy → it runs through a persistent job queue (
src/jobs.js) with capped concurrency, so the MCP request returns instantly.The image is large (Chrome + ffmpeg + the full toolchain) and the build clones upstream at a pinned commit (
HF_REF) for reproducibility.Not a fork of upstream — this repo carries only the server + deployment recipe.
Available Tools
11 toolscancel_jobB
Cancela un job en cola o en ejecución.
Inputs: job_id (required).
create_projectA
Crea un proyecto HyperFrames nuevo a partir de un ejemplo. Devuelve el nombre del proyecto.
Inputs: name (required), example.
get_jobA
Estado y log de un job (render o snapshot) por su job_id.
Inputs: job_id (required).
lint_projectA
Corre el linter de HyperFrames sobre un proyecto (accesibilidad, layout, motion). Salida JSON.
Inputs: project (required), verbose.
list_compositionsA
Lista las composiciones de un proyecto (archivos .html). Salida JSON.
Inputs: project (required).
list_jobsA
Lista los jobs recientes (más nuevos primero) y el estado de la cola.
Inputs: limit.
list_projectsB
Lista los proyectos HyperFrames del workspace (cada uno con su index.html).
Inputs: no named parameters.
render_videoA
Renderiza un proyecto/composición a MP4 (u otro formato: webm, mov, gif, png-sequence). Por defecto ENCOLA el trabajo y devuelve un job_id — el render es pesado y no debe bloquear la request; sigue el avance con get_job / wait_job. Usa wait=true para clips cortos.
Inputs: project (required), fps, wait, format, +4 more.
snapshot_framesA
Captura frames PNG de una composición para control visual de calidad. Por defecto ENCOLA y devuelve un job_id (get_job / wait_job).
Inputs: project (required), at, wait, frames, +1 more.
wait_jobB
Bloquea hasta que el job termine (o se agote el timeout). Útil para agentes sin polling.
Inputs: job_id (required), timeout_ms.
write_project_fileB
Escribe (o crea) un archivo dentro de un proyecto del workspace: HTML, CSS, SVG, JSON… Crea los directorios necesarios. Para binarios (PNG/JPG/MP4) usa encoding=base64. Permite crear un proyecto nuevo desde cero escribiendo su index.html.
Inputs: path (required), content (required), project (required), encoding.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource and action: projects, compositions, linting, rendering, snapshots, and job management (get, list, wait, cancel). No two tools overlap in purpose; even the job-related tools have clearly separated responsibilities.
All tool names follow the verb_noun snake_case pattern (e.g., list_projects, render_video, cancel_job). The convention is uniform with no stylistic mixing, making the API predictable and easy to navigate.
With 11 tools, the server is well-scoped for managing HyperFrames projects, covering creation, editing, linting, rendering, snapshots, and asynchronous job lifecycle. Each tool earns its place in the workflow without bloat.
The tool surface covers the core lifecycle: create/list projects, write files, lint, render, snapshot, and manage jobs. Minor gaps like delete_project or read_file exist, but agents can accomplish primary tasks without dead ends.
Maintenance
Related MCP Connectors
Hosted video MCP server for branded explainers and reference-driven edits.
Compose, edit and render video with your AI agent. Turn footage into finished edits with content-aware reframing, word-timed captions and motion graphics. Hosted MCP with OAuth sign-in; cloud processing uses credits.
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceEnables agents to create AI music videos and audio-reactive visuals from songs through MCP, including style discovery, music search, rendering, webhook registration, and media management.1MIT- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to run project-scoped video editing workflows: propose and approve editing strategies, apply validated plans, review immutable versions, and export final renders via FFmpeg, with durable persistence and approval gates.1MIT
- AlicenseNot gradedqualityDmaintenanceExposes video generation and editing tools to MCP-capable clients, enabling text-to-video, image-to-video, video editing, reusable voice and character profiles, and task status queries through natural language.4MIT
- FlicenseCqualityBmaintenanceProvides a durable MCP media pipeline for image, video, audio, and storyboard generation, with FFmpeg composition, provider routing, and resumable long-running jobs.21-