CueFrame — MCP, CLI and video API

CueFrame is a hosted service for composing, editing and rendering video. Connect your agent over MCP, automate an edit from the CLI, or integrate the REST API into your application. Each surface works with editable projects containing clips, captions and motion graphics, and renders them to MP4.

First render · Connection guide · Templates · API reference · Agent documentation index

A frame from the Yosemite Peregrines template. Watch the video and try the same edit.

MCP and agent plugin

For Claude Code, Codex, Cursor, VS Code, and other supported local agents, run this in your terminal with Node.js 24 or newer:

npx -y cueframe@0.8 install

The installer detects supported agents and adds the hosted CueFrame MCP endpoint to their configuration. It installs the skills in ~/.agents/skills and ~/.claude/skills, preserving locally modified skills by default. It can update multiple detected clients; use --dry-run to inspect the changes first.

Restart your agent session. Then ask:

Use CueFrame's get_account tool to check my connection and show my available credits.

Your client may prompt you to authenticate or open a browser. Sign in to CueFrame and authorize the connection; interactive OAuth clients need no API key. Cloud operations use credits. Check your balance and estimated costs before starting paid work; see cloud rates.

ChatGPT and Claude Desktop: use your client's hosted connector setup with https://api.cueframe.ai/v1/mcp, then authenticate. The terminal installer does not configure ChatGPT. See the connection guide and CueFrame connection skill for supported paths. Skills installation and hosted connector setup are separate steps.

Already connected? Skip installation and give your agent a video task. If CueFrame's tools do not appear, restart the client and check its MCP connection settings.

Make your first video

Try the Yosemite first-render walkthrough: render a template, change one word, and render again from the same project.

1. Download the full original footage from the National Park Service as yosemite-peregrines.mp4. Use the original source, because the finished demo has its title baked in. Follow the source's download and reuse guidance.

2. Give your connected agent the source file and this instruction:

   Use CueFrame to start the yosemite-peregrines template from cueframe-ai/cueframe-templates with this original video. Load template.cueframe and its prepared subject matte. Preview the editable project and estimate cloud costs. After I approve the render, return the MP4 link and project ID.

3. After the first render, ask:

   In that same project, replace the behind-subject title PHENOMENAL with EXTRAORDINARY. Preserve the footage, spoken captions, audio, timing, placement, and depth. Preview the changed title, estimate the render cost, and render after I approve.

The template selects 83.616–93.359 seconds of the original video. You should get two MP4s from one editable project. Uploading footage and running cloud operations use credits; the two renders are billed separately.

The project stays editable: the desktop editor shows the title as a separate layer, alongside footage and captions. Watch the title change.

What happens over MCP?

flowchart LR
    A[Your request + footage] --> B[Your agent + CueFrame skills]
    B --> C[Hosted CueFrame MCP]
    C --> D[Editable project + preview]
    D --> E[Render job → MP4 link]

The agent inspects available tools, checks your account, prepares media and the project, previews changes, and submits a render. Long-running operations return IDs; the agent waits for completion and gives you the result. You do not need to write the tool calls yourself. The detailed quickstart explains the individual calls.

For your next video, describe the result and provide the inputs:

Turn this interview into a 20-second vertical clip with word-timed captions. Preview the strongest moment and show estimated costs before rendering.

Find an image-carousel component for these product photos. Show suitable choices and their required inputs before creating the video.

Change only the final title in this project. Keep the rest of the edit unchanged.

Other installation options

Choose one setup path. A plugin installs the skills and hosted MCP configuration together. A server-only connection adds tools; skills provide the workflow guidance.

claude plugin marketplace add cueframe-ai/cueframe-mcp
claude plugin install cueframe@cueframe

codex plugin marketplace add cueframe-ai/cueframe-mcp
codex plugin add cueframe@cueframe

gemini extensions install https://github.com/cueframe-ai/cueframe-mcp

npx skills add cueframe-ai/cueframe-mcp

claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp

Skills included

Skills teach the agent how to carry out video tasks. You describe the task; the agent selects the relevant guidance.

Claude Code's session hook and Cursor's rule help select the entry point. Other hosts load the installed skills through their own mechanisms. Scoped edits should preserve unrelated work.

CLI

Use the CLI for explicit video commands, shell scripts and structured JSON output. It connects to the hosted API; it does not run a local renderer. Requires Node.js 24 or newer.

npx -y cueframe@0.8 --help
npx -y cueframe@0.8 login
npx -y cueframe@0.8 api GET /v1/me --json
npx -y cueframe@0.8 describe --json

login opens the browser to authenticate. Headless scripts can supply CUEFRAME_API_KEY. The account request checks your connection and credits; describe lists command arguments and options without making an API call.

CLI guide · CLI walkthrough · Templates · npm package

API and TypeScript SDK

Use the REST API to create projects, import media, change compositions and follow render jobs from your application. Requests go to https://api.cueframe.ai with an API key from your account. Check your account before metered operations; cloud rendering and processing use credits.

For TypeScript or JavaScript on Node.js 24+, install the typed client:

npm install @cueframe/sdk

import { account, createClient } from "@cueframe/sdk";

if (!process.env.CUEFRAME_API_KEY) throw new Error("Set CUEFRAME_API_KEY");
createClient({
  baseUrl: "https://api.cueframe.ai",
  apiKey: process.env.CUEFRAME_API_KEY,
});
const result = await account.getAccount();
console.log(result.plan, result.entitlements);

Other languages can call REST directly or generate a client from the versioned public OpenAPI contract. The SDK is a client for the hosted service, not the server implementation.

API walkthrough · API reference · SDK guide · Render example · npm package

What this repository contains

This repository contains the agent plugin, developer toolkit, and registry files. The hosted MCP server is maintained separately in the application repository. You connect to CueFrame's hosted service; cloning this repository does not run that service locally.

Contribute

Documentation, client examples, skill improvements, and toolkit fixes are welcome. Start with good first issues or read CONTRIBUTING.md for setup, generated-file rules, tests, and commit sign-off.

Edit skills in root skills/; change generated API clients through their documented inputs. Report hosted-service problems in this repository's issue tracker with reproduction steps and a request ID when available. Report vulnerabilities privately using SECURITY.md. Community participation follows the Code of Conduct.

Published packages

Package	Purpose	npm
@cueframe/api-contract	The public OpenAPI document, its reviewed operation inventory and a content-addressed manifest: the only input the generated clients read.
@cueframe/sdk	Typed fetch-based TypeScript client with zod request schemas and SSE helpers for render and compose progress.
cueframe	The CLI: login, projects, media, compositions, renders, exports and install, every command with --json.
@cueframe/skills	The skills/ tree as an npm package (SKILLS_DIR from @cueframe/skills/dir), for programs that copy or embed the skills.

The MCP server itself (@cueframe/mcp) is a private package maintained in the application repository; this repository ships the contract it is generated from, the clients, the plugin, the registry entry (server.json) and a discovery shim, not the server.

How the contract flows

private API ──sync──▶ api/openapi.json (+ scene-schema.json, scene-examples.json, contract-manifest.json)
                          │
                          ├──▶ packages/api-contract/dist  ──publish──▶  @cueframe/api-contract@x.y.z ──▶ the MCP server's generators, third parties
                          └──▶ packages/sdk/src/generated        (Orval: operations, models, zod)

The private API publishes its OpenAPI projection into api/; pnpm generate:api-consumers vendors the scene schema into the contract and regenerates the SDK from it. This is the one copy of the contract: the MCP server's generators in the application repository and every other consumer read it from the @cueframe/api-contract npm package, whose version moves with the contract (pnpm check:contract-version fails an api/*.json change without a bump), so the tool surface and the SDK always describe one contract. Nothing under api/ or a generated/ directory is hand-edited: pnpm check:api-inputs proves the three api/*.json inputs came from one sync, and pnpm check:api-consumer-drift proves the generated trees match them byte for byte.

How the skills flow

Root skills/ is the single source: the plugin hosts read it from this repository, and pnpm build copies it into packages/skills/dist (published as @cueframe/skills) and from there into the CLI's dist/skills for cueframe install. pnpm check:plugin validates every skill and manifest; agents/openai.yaml and assets/icon.svg beside each skill are generated.

Registry files

• server.json: the MCP registry entry for the hosted server (ai.cueframe/cueframe, remotes only). pnpm check:server-json validates it against the vendored registry schema; the registry job of the publish workflow publishes it.
• glama.json: the Glama listing's maintainer file.
• glama/ and the Dockerfile: a stdio discovery shim that replays a snapshot of the hosted server's tool list and instructions for registries that introspect over stdio. It is not a server (see below).

Hosted, desktop-local, and the discovery shim

The hosted service, desktop integration, and registry shim serve different purposes.

• The hosted server at https://api.cueframe.ai/v1/mcp is the product. Every install line above talks to it; it authenticates with OAuth or an API key and does the composing and rendering. Its package, @cueframe/mcp, is private.
• The CueFrame desktop app ships its own local MCP server for the project you have open. It needs no account and is connected through the connection file the app publishes; the app's Agents settings show the exact command, and https://docs.cueframe.ai explains it. Its bundled binary is called cueframe-mcp; it lives inside the app bundle.
• This repository's discovery shim (glama/server.mjs, built by the Dockerfile) is not a server. It replays a snapshot of the hosted server's tool list and instructions over stdio so registries that build an image can list the tools without an account; every tools/call answers with a pointer to the hosted server. glama/refresh-snapshot.md says where the snapshot comes from.

Repository layout

• skills/<name>/SKILL.md: the skill. agents/openai.yaml and assets/icon.svg beside it are generated (pnpm build:plugin).
• .claude-plugin/, hooks/, .mcp.json: Claude Code plugin, session router and server.
• .codex-plugin/, .agents/plugins/, mcp.json: Codex and ChatGPT plugin and marketplace.
• .cursor-plugin/, rules/: Cursor plugin and the always-on rule.
• gemini-extension.json, skills.sh.json, plugin.json: Gemini CLI, skills.sh, the portable manifest (agent-plugins.org).
• api/, packages/, tools/, scripts/: the contract, the four npm packages, their generators and checks (scripts/plugin/ holds the plugin's).
• server.json, glama.json, glama/, Dockerfile: the registry files.
• examples/, llms-install.md: per-client setup and the agent-readable install guide.

Development

pnpm install
pnpm check      # input provenance, the contract version rule, the public-contract gate, server.json, the plugin, and tsc --noEmit in sdk and cli
pnpm build      # stamps the plugin manifests and skill cards, then tsup in every package; the CLI packages the skills
pnpm test

Node 24 or newer and pnpm (see .nvmrc and packageManager). CONTRIBUTING.md explains which paths are generated, the skill contract and how a change travels; AGENTS.md is the same for an agent working in this tree; llms-install.md connects a client step by step.

License

Apache-2.0. See LICENSE and NOTICE.