Use with agents

An agent can't watch a video, so Kinetograph gives it two things:

• A skill that teaches it a loop: write, look, check, render. The agent can write a Remotion-style TSX project or an HTML page.
• An MCP server that runs each CLI command as a tool and returns frames as images.

The MCP serverCopy Anchor Link

The server is npx kinetograph mcp, over stdio. It has one tool for each CLI command except studio, which keeps running until stopped. Studio has its own chat with your coding agent and gives it these tools.

A tool takes the same arguments as its command. Command names with a space use an underscore, so audio analyze is audio_analyze. An error comes back as { "error": { "code", "message" } }.

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

Set up the MCP serverCopy Anchor Link

Every client runs the same command, npx -y kinetograph mcp. You need Node 22 or newer.

Claude CodeCopy Anchor Link

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 DesktopCopy Anchor Link

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"]
    }
  }
}

Restart Claude Desktop after saving.

CursorCopy Anchor Link

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 CLICopy Anchor Link

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 skillsCopy Anchor Link

There are two skills:

• kinetograph teaches the write, look, check, render loop. It covers how a project is laid out, sound, Remotion compatibility, doctor and the CLI flags an agent needs.
• kinetograph-migrate moves an existing Remotion project onto Kinetograph. 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 --list   # show what it found, install nothing
npx skills add 0xS4N4TG/kinetograph          # install

The skills also come inside the npm package. To copy them to where Claude Code looks for skills:

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

For one project only, copy them to .claude/skills/ in that project instead. Other agents that read SKILL.md files can use the same folders.

One more skill, kinetograph-taste-clone, lives in kinetograph-ui. It turns a reference reel into a spec or a reusable style. See Match a reel, keep its taste.

The loop the skill teachesCopy Anchor Link

1. Write a project file that calls registerRoot.
2. Look. strip shows twelve labelled frames at once, still shows one, and onion shows a motion path.
3. Check without looking at pixels. inspect gives each layer's position and bounds. lint reports overflow, off-canvas layers, and missing fonts and assets. check catches type errors.
4. Fix and go back to step 2. A still takes well under a second.
5. Render with render. Use --draft for a half-size look first. Run doctor before a long render of 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.