Use with agents

Give a coding agent the Kinetograph skill and MCP tools so it can write, check and render videos.

An agent can't watch a video, so Kinetograph gives it two things instead. A skill teaches it a loop: write, look, check, render. An MCP server lets it run each CLI command as a tool and see frames as images.

What an agent gets

The skill is a folder with a SKILL.md that the agent reads. It covers the loop below, how a project is laid out (registerRoot, Composition, the native elements and effects), sound, Remotion compatibility and doctor, and the CLI flags an agent needs.

The MCP server is npx kinetograph mcp, over stdio. It has one tool for each CLI command except studio, which keeps running until stopped. A tool takes the same arguments as its command. Command names with a space use an underscore. An error comes back as { "error": { "code", "message" } }.

Tool	What it does
`compositions`	List the compositions of a project
`still`	Render one frame to a PNG; returns the image
`strip`	Contact sheet of evenly spaced frames, labelled with frame and time; returns the image
`onion`	Frames of a range blended over one another, to show a motion path; returns the image
`inspect`	The scene graph at a frame: layers, bounds and resolved styles
`lint`	Text overflowing its box or the canvas, layers off the canvas, overlapping text, missing fonts and assets, type errors, and what the engine can't draw from a Remotion project
`check`	Type errors in the project (`tsc --noEmit`), such as a misspelled prop that renders without an error
`doctor`	What a project holds that the engine cannot draw, and in which frames; with no entry, what this install can do
`render`	Render frames to a video with audio
`snapshot`	Compare frames with the approved PNGs in `__snapshots__/` next to the entry
`audio_analyze`	Loudness (LUFS), true peak, clipping and silences of the mixed audio
`bench`	Milliseconds per frame for each stage
`effects`	List the effects and their parameters

For still, strip and onion, output is optional: the server writes a temporary PNG and returns it. render needs output.

Set up the MCP server

Every client below runs the same command, npx -y kinetograph mcp. You need Node 22 or newer, and a GPU that wgpu supports (Metal on macOS).

Until 0.1.0 is on npm, run the server from a clone: build the repo, then use node as the command with the arguments /path/to/kinetograph/packages/cli/dist/cli.js and mcp (node packages/cli/dist/cli.js mcp from the repo root).

Claude Code

claude mcp add kinetograph -- npx -y kinetograph mcp

This saves the server for the current project. Add --scope project to write it to .mcp.json for the team, or --scope user to use it in every project.

Claude Desktop

Open Settings, then Developer, then Edit Config. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "kinetograph": {
      "command": "npx",
      "args": ["-y", "kinetograph", "mcp"]
    }
  }
}

Quit and restart Claude Desktop after saving.

Cursor

Put this in .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project.

{
  "mcpServers": {
    "kinetograph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kinetograph", "mcp"]
    }
  }
}

OpenAI Codex CLI

Add a table to ~/.codex/config.toml:

[mcp_servers.kinetograph]
command = "npx"
args = ["-y", "kinetograph", "mcp"]

Or run codex mcp add kinetograph -- npx -y kinetograph mcp. codex mcp list shows the result.

Install the skills

There are two skills. kinetograph teaches the write, look, check, render loop. kinetograph-migrate moves an existing Remotion project onto Kinetograph: it runs doctor, fixes each finding with reference files for 3D, tooling and unsupported content, and renders with --strict. See Migrate from Remotion.

Install both from the GitHub repo with the skills CLI (it asks which agents to install them for):

npx skills add 0xS4N4TG/kinetograph

The skills also come inside the npm package. Once the package is installed in a project, you can copy them to where Claude Code looks for skills instead:

mkdir -p ~/.claude/skills
cp -R node_modules/kinetograph/skills/kinetograph node_modules/kinetograph/skills/kinetograph-migrate ~/.claude/skills/

For one project only, copy it to .claude/skills/kinetograph/ in that project instead. Other agents that read SKILL.md files can use the same folder in their own skills folder.

You can also install it from the repository with the skills CLI, which finds both skills in packages/cli/skills/ and asks which agents to install it for:

npx skills add 0xS4N4TG/kinetograph --list   # show what it found, install nothing
npx skills add 0xS4N4TG/kinetograph          # install

The loop the skill teaches

Write a project file that calls registerRoot.
Look. strip shows twelve labelled frames at once, still shows one, and onion shows a motion path. The agent reads the PNG.
Check without looking at pixels. inspect gives each layer's final position and bounds at a frame. lint reports overflow, off-canvas layers, missing fonts and assets, with the frame and layer id. check catches type errors that render without complaint.
Fix and go back to step 2. A still takes well under a second.
Render with render. Use --draft for a half-size look first, and doctor before a long render on a project that uses HTML elements or CSS, to see what the render will leave out.

A prompt as short as "make a 5 second title card for X, check it with strip and lint, and render it to out/title.mp4" is enough to start this loop.

What an agent getsCopy Anchor Link

Set up the MCP serverCopy Anchor Link

Claude CodeCopy Anchor Link

Claude DesktopCopy Anchor Link

CursorCopy Anchor Link

OpenAI Codex CLICopy Anchor Link

Install the skillsCopy Anchor Link

The loop the skill teachesCopy Anchor Link

On this page