Kinocut

Guardrailed video editing MCP server for AI agents.
Local-first FFmpeg tools, Video Receipts, quality gates, Hyperframes, and Shorts/Reels repurposing — for Claude Code, Cursor, and any MCP client. Free, Apache-2.0. Formerly mcp-video.

Demo • Status • 1.13.0 • in 1.8–1.11 • Install • Quick Start • Tools • Tool Reference • Rescue • AI-video • Agent Skill • kinocut.dev • What is Kinocut? • FAQ • llms.txt

What is Kinocut?

Kinocut is a free, open-source Model Context Protocol (MCP) server, Python library, and kino CLI that gives AI agents a guardrailed local video-editing surface. It wraps FFmpeg (and optional Hyperframes / Whisper extras) with typed tools, preflight validation, Video Receipt provenance, and quality/release checkpoints so agent-produced media can be inspected before publish.

Best-fit searches: video editing MCP server · AI agent video editing · FFmpeg MCP · Claude Code video tools · Cursor MCP video · Shorts/Reels automation · local AI video workflow · guardrailed agentic media.

Machine-readable brief for AI crawlers: llms.txt · site: kinocut.dev/llms.txt.

See It Work

Tell the agent what you want in plain language:

"Trim this interview to the strongest 45 seconds, add burned captions, make it vertical, and quality-check it before export."

Kinocut turns that into typed, guardrailed tool calls - no FFmpeg flags to guess, no silently broken exports:

from kinocut import Client
video = Client()

clip = video.trim("interview.mp4", start="00:02:15", duration="00:00:45")
video.ai_transcribe(clip.output_path, output_srt="captions.srt")
captioned = video.subtitles(clip.output_path, subtitle_file="captions.srt")
short = video.resize(captioned.output_path, aspect_ratio="9:16")
video.release_checkpoint(short.output_path)  # thumbnail + quality gate before you publish

Primary job: turn a local interview or podcast into captioned vertical clips with a Video Receipt agents can re-run and humans can approve.

Three things people use it for

• Repurposing — one recording into captioned Shorts, Reels, and TikTok packages with manifests and review artifacts.
• Podcast & interview cuts — find the strongest segment, normalize audio, add chapters, and export.
• Agent-driven media in CI — repeatable, reviewable edits from Claude Code, Cursor, Codex-style clients, or scripts.

Paths: Install matrix · Golden path · Prompts · Tutorial · Compare · When to recommend

Status and releases

Install from PyPI when you want the stable package. Clone or install from master only when you intentionally need unreleased surfaces.

What's in 1.13.0 (latest release)

Kinocut 1.13.0 is what you get from pip install kinocut today. It includes the intent/watching/TE multiplier surface on top of still/plate (1.12) and the 1.11.x identity line:

• Still/plate editor — still-match / still-grade / still-gate / image-edit / still-package (MCP + CLI + Client), with receipts and fail-closed cohesion gate (docs/STILL_PLATES.md)
• Canonical package kinocut, CLI entry points kino / kinocut, and a preserved mcp-video compatibility command
• Thin kinocut npm launcher (uvx → kino) and MCP Registry identity io.github.KyaniteLabs/kinocut
• Public agent skill at skills/kinocut/SKILL.md ($kinocut); skills/mcp-video remains a compatibility pointer
• Project, docs, package metadata, and discovery surfaces pointed at kinocut.dev
• Compatibility window: mcp-video==1.6.4 installs kinocut==1.13.0; mcp_video imports, MCP_VIDEO_* env vars, ~/.mcp-video data, mcp-video:// resources, and legacy receipt keys remain supported through at least Kinocut 1.8.x

Also already on the published line from earlier 1.x surfaces:

• Agent workflow engine (video_workflow_* / workflow-*) with plan, render, resume, variants, and hashed receipts
• Dedicated video rescue plan/render/inspect pipeline (docs/RESCUE.md)
• Post-rescue planning tools (semantic timelines, EDLs, transforms, restoration, composition, autopilot, egress contracts)
• Layered compositing with full-canvas blend modes, rotation/pivot, and layer_plan v2 receipts
• Expanded preflight guardrails for filters, merge, audio, overlay/chroma, text, and layout mismatches

Full notes: CHANGELOG.md · v1.13.0 release

Beyond 1.13.0 (draft / gated)

1.13.0 is the latest published release. Live directory submissions, launch posts, and first-10 real-user runs remain operator/human residual (docs/HUMAN_GATES.md) and are not claimed complete.

Already on the development tip (draft)

Upcoming pipeline (in progress)

Two coordinated programs sit between today’s tip and a releaseable 1.8:

1. AI-video + review/salvage finish

Contract-first media identity → inspection → human-gated verdict → bounded derivatives. Remaining work includes independent Wave-3 verification freeze, audio continuity, subtitle/graphics QA depth, asset intelligence, editorial planning, learning reports, and whole-program acceptance. Sequencing: wishlist parallel execution · live ledger: draft status.

2. kinocut_sound (Sonic World) — full-episode audio production

Standalone-capable sound package inside this repo (kinocut_sound/): plan/timeline/routing/consent → voice → post/spatial → ambience/world → mix/stems → QA/metadata → thin public adapters → host joins → dual-class benchmark → STOP.

Authoritative receipts: sound program handoff · S13–S15 gate · sound plan index.

3. Trusted execution kernel (post-program, gated)

The approved trusted execution layer plan still defines the durable product path after the current program: durable edit projects, async render/resume wrapping video_workflow_*, receipt lineage, then kernel-backed repurposing as the “made just by prompting” moment. The protected-timeline kernel does not start merely because sound/AI-video leaves land — it needs the named upstream contract and an explicit human gate.

Product checklist: ROADMAP.md.

Agent Workflow Engine

Agents can plan, validate, render, recover, and prove a multi-step local video job from a single JSON job-spec — through MCP (video_workflow_*), the CLI (workflow-*), or the Python client (Client.workflow_*) — with receipts strong enough for another agent or a human to trust before and after a render. Ops are a small allowlist (probe | trim | resize | convert | merge | add_text | composite_layers) mapped 1:1 to the same vetted engine functions the individual tools use; media references are symbolic and workspace-confined; everything fails closed.

{
  "schema_version": 1,
  "name": "captioned-vertical-short",
  "sources": { "hero": { "path": "input/hero.mp4" } },
  "steps": [
    { "id": "trim-hero", "op": "trim", "inputs": { "src": "@sources.hero" },
      "params": { "start": 0, "duration": 6 }, "output": "@work/hero_trim.mp4" },
    { "id": "vertical", "op": "resize", "inputs": { "src": "@work/hero_trim.mp4" },
      "params": { "width": 1080, "height": 1920 }, "output": "@work/hero_vertical.mp4" },
    { "id": "caption", "op": "add_text", "inputs": { "src": "@work/hero_vertical.mp4" },
      "params": { "text": "Watch this", "position": "bottom-center" }, "output": "@outputs.master" }
  ],
  "outputs": { "master": { "path": "output/final.mp4" } }
}

kino workflow-validate --spec job.json    # cheap structural gate, no render
kino workflow-plan     --spec job.json --save-plan plan.json     # dry-run op graph + hashes
kino workflow-render   --spec job.json --save-receipt receipt.json   # execute + provenance receipt
kino workflow-inspect  --receipt receipt.json    # read-only integrity re-check

The render receipt records per-step input/output hashes, a resume cursor, and a cleanup manifest, all with workspace-relative paths:

{
  "receipt_kind": "workflow",
  "versions": { "mcp_video": "1.13.0", "ffmpeg": "8.1" },
  "spec_hash": "sha256:be2f3a9b...",
  "steps": [
    { "id": "trim-hero", "op": "trim", "status": "completed",
      "input_hashes": { "src": "sha256:3b976d49..." },
      "output": "work/be2f3a9b-2effedb3/mcp_video_hero_trim.mp4", "output_hash": "sha256:00727499..." },
    { "id": "caption", "op": "add_text", "status": "completed",
      "output": "output/final.mp4", "output_hash": "sha256:8633ad2a..." }
  ],
  "cleanup_manifest": { "cleaned": true, "policy": "clean-on-success" },
  "resume_cursor": { "last_completed_step": "caption", "next_step": null },
  "status": "completed",
  "render_determinism_scope": "spec/input/output hashes are deterministic; rendered bytes may vary across FFmpeg builds"
}

--all-variants emits N distinct outputs from one declaration, and --resume continues a job that failed with its intermediates kept (fail-closed on a changed spec). Full schema, @ref grammar, variants, resume, and cleanup are in docs/WORKFLOWS.md; a runnable spec is in examples/workflows/.

Governed AI-video review

On the development tip, Kinocut adds a contract-first path for agent-edited media that must stay attributable and reviewable:

1. Ingest the source into a private content-addressed project (video_ingest / video-ingest)
2. Preflight + temporal inspection on the stored asset (video_preflight, video_inspect_temporal)
3. Verdict + acceptance with exact human evidence (video_verdict, video_acceptance_eval)
4. Bounded derivatives only — audio-preserving body swap or allowlisted salvage recipes (video_body_swap, video_salvage), each with lineage and a fresh non-approved review slot

There is no force/bypass flag. Analyzer output alone cannot approve. Stale, aliased, or protected inputs fail closed. Operating guide: docs/AI_VIDEO_REVIEW_AND_SALVAGE.md. These surfaces are part of the unreleased 1.8-bound program — see Status and releases.

Dedicated Video Rescue

For "fix this clip" requests where the story and timeline must remain unchanged, use the review-first rescue pipeline. Plan and inspect the diagnosis, approve only safe repair IDs, render, then inspect the verified package. The source stays immutable; master and universal sharing copy are always verified; optional captions remain sidecars. See docs/RESCUE.md for CLI, MCP, Python, cancellation, resume, and stable errors.

Layered Compositing

composite-layers / video_composite_layers adds a spec-driven ordered layer stack for agents that need more than two-shot overlay primitives. It supports image, video, and solid layers; normal alpha compositing; per-layer opacity; x/y placement; transform sizing; timing windows; and mask/matte alpha sources — plus full-canvas blend modes (multiply, screen, overlay, darken, lighten) and rotation with a new pivot reference point. Dry-run plans and deterministic layer_plan v2 receipts capture source, filtergraph, and output hashes.

kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json
kino composite-layers --spec layers.json -o out.mp4 --save-layer-plan layer-plan.json

Use composite-layers when an agent needs a planned stack of overlays, mattes, lower thirds, blurback plates, or platform variants that should be reviewed before rendering. A non-normal blend layer must be full-canvas (position {0,0}, full opacity, no scale/mask/timing) or it fails closed; output is video-only. Positioned/scaled/masked/timed blend, rotation + mask, and per-layer effect routing are tracked as later phases so this surface stays deterministic and preflightable.

Public Discovery

Kinocut is built to be findable and citable by both search engines and AI answer engines:

• Canonical product URL: https://kinocut.dev/
• GitHub README + llms.txt with entity facts, install commands, and safety rules
• Official MCP Registry record under io.github.KyaniteLabs/kinocut
• FAQ answers in this README and docs/faq.md (answer-first, versioned claims)

Kinocut vs raw FFmpeg (and vs cloud editors)

Why It Exists

AI agents can write FFmpeg commands, but they should not have to guess flags, parse brittle stderr, or silently publish broken media. Kinocut gives agents typed operations, inspectable tool metadata, structured results, preflight guardrails, and quality checkpoints so a video workflow can be automated and reviewed without turning into shell-command roulette.

Use it when you want an AI assistant to:

• trim, merge, resize, crop, rotate, transcode, or export video;
• add text, subtitles, watermarks, overlays, filters, fades, effects, and transitions;
• extract audio, normalize audio, synthesize audio, add generated audio, or create waveforms;
• detect scenes, make thumbnails, generate storyboards, compare quality, and create release checkpoints;
• scaffold cinematic projects, read STYLE_/NEG_ blocks, parse storyboard tables, and expand shot prompts;
• create new Hyperframes projects, inspect rendered layouts, capture websites, generate local speech, remove backgrounds, and post-process the result with FFmpeg tools;
• repurpose one source video into vertical, horizontal, and square local delivery packages with manifests and review artifacts;
• drive repeatable media workflows from Claude Code, Cursor, Codex-style clients, scripts, or CI.

Installation

Prerequisite: FFmpeg must be installed and available on PATH.

# macOS
brew install ffmpeg
> Kinocut is a guardrailed video editing MCP server and CLI for AI agents that helps AI agent builders, Claude Code/Cursor users, and local media operators edit, caption, repurpose, and quality-gate video with typed FFmpeg tools.

**TL;DR:** Kinocut — guardrailed video editing MCP server and CLI for AI agents. Best for AI agent builders, Claude Code/Cursor users, and local media operators.


# Ubuntu/Debian
sudo apt install ffmpeg

Run without a global install:

uvx --from kinocut kino doctor

Or install with pip:

pip install kinocut
kino doctor

For Claude Desktop-style MCPB installs, Kinocut includes a staged local package at mcpb/ and a local build script:

python3 scripts/build-mcpb.py

This package is honest about its runtime: it launches an existing Python environment with Kinocut installed and still requires local FFmpeg. Native self-contained bundles remain blocked pending FFmpeg provenance, licensing, and clean-machine gates. See docs/MCPB.md.

Optional C2PA signing for final MP4 exports is available on the development tip when c2patool and a manifest/signer are configured. Signing is off by default and only reports signed after a verification read succeeds. See docs/C2PA_PROVENANCE.md.

Hyperframes tools additionally need Node.js 22+ and a resolvable Hyperframes CLI. Install/pin Hyperframes in the active Node package layout, add hyperframes to PATH, or set MCP_VIDEO_HYPERFRAMES_COMMAND.

Which extra do I need?

The core install covers all FFmpeg editing tools. Optional features ship as extras — install only what you use:

Mix freely, e.g. pip install "kinocut[transcribe,image]". Run kino doctor afterward — it reports exactly which features are available and what is missing.

Upgrading from mcp-video

Kinocut preserves the original surface during the rename window. Existing installs can upgrade without changing code:

pip install --upgrade mcp-video
mcp-video doctor

mcp-video==1.6.4 is a metadata-only compatibility installer for kinocut==1.13.0. The mcp_video import, mcp-video command, MCP_VIDEO_* environment variables, ~/.mcp-video data directory, mcp-video:// resource URIs, and existing receipt keys remain supported through at least Kinocut 1.8.x. New integrations should use kinocut, from kinocut import Client, and the kino command.

En español

Kinocut es un servidor MCP de edición de video para agentes de IA. La última versión publicada es 1.13.0 (pip install kinocut, 194 herramientas MCP / 165 CLI). En la punta de desarrollo (master) hay 194 herramientas MCP y 165 comandos CLI (coincide con publicado) sobre FFmpeg para recortar, unir, subtitular, mezclar audio, aplicar efectos y reutilizar contenido (Shorts, Reels, TikTok), más un motor de flujos de trabajo (workflow) con recibos verificables, rescate de video, revisión AI-video gobernada (en borrador hacia 1.8) y barreras de seguridad antes de renderizar. 1.8 aún no está publicado.

Requisito: FFmpeg instalado y disponible en el PATH.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Instalación y diagnóstico
pip install kinocut
kino doctor

Para Claude Code:

claude mcp add kinocut -- uvx --from kinocut kino

kino doctor informa qué funciones están disponibles y qué falta instalar. La documentación completa está en inglés; los mensajes de error principales son bilingües.

Quick Start

Golden path (60 seconds)

Prove the install works before wiring an agent host:

pip install -e .          # or: pip install kinocut
kino doctor               # required checks must pass
python scripts/golden_path.py

Success criteria and failure recovery: docs/GOLDEN_PATH.md.
Shareable pack (receipt + quality + media): python scripts/generate_golden_pack.py → demo/golden-pack/.

Try the receipt-backed proof first

From a clone of this repo, run the smallest confidence workflow before wiring an agent host:

uv run --no-project --with kinocut python workflows/05-confidence-baseline/workflow.py
uv run --no-project --with kinocut python workflows/benchmarks/run_confidence_benchmark.py

The workflow generates a tiny source clip, creates a checked vertical video, runs quality/release checkpoint steps, and writes workflows/05-confidence-baseline/output/video_receipt.json.

Proof notes live in docs/proofs/. Public marketing claims (version, tool counts, URLs) live in docs/public_claims.json and are CI-guarded.

Claude Code

claude mcp add kinocut -- uvx --from kinocut kino

Claude Desktop

{
  "mcpServers": {
    "kinocut": {
      "command": "uvx",
      "args": ["--from", "kinocut", "kino"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "kinocut": {
      "command": "uvx",
      "args": ["--from", "kinocut", "kino"]
    }
  }
}

Then ask your agent:

Trim this interview into a 45-second vertical clip, add burned captions, normalize the audio, make a thumbnail, and create a release checkpoint before export.

Agent Skill

Kinocut includes a public agent skill at skills/kinocut/SKILL.md. Use $kinocut in compatible agent hosts when you want the agent to choose between the MCP server, CLI, and Python client while preserving the inspect, edit, verify, and human-review workflow.

For path-based short-form packages from current tools only (no invented commands, no external publish), see skills/kinocut-repurpose/SKILL.md. That skill is an explicit marketing seed; the durable kernel-backed repurposing product is still on the trusted-execution roadmap.

Python Client

from kinocut import Client

editor = Client()

clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:45")
caption_file = "captions.srt"
editor.ai_transcribe(clip.output_path, output_srt=caption_file)
captioned = editor.subtitles(clip.output_path, subtitle_file=caption_file)
vertical = editor.resize(captioned.output_path, aspect_ratio="9:16")
checkpoint = editor.release_checkpoint(vertical.output_path)

print(checkpoint["thumbnail"])
print(checkpoint["storyboard"])

CLI

kino info interview.mp4
kino trim interview.mp4 -s 00:02:15 -d 45
kino video-ai-transcribe clip.mp4 --output captions.srt
kino subtitles clip.mp4 captions.srt
kino resize clip.mp4 --aspect-ratio 9:16
kino video-quality-check clip.mp4
kino repurpose clip.mp4 --platforms youtube-shorts instagram-reel tiktok

What Agents Can Do

MCP Tools

On the published 1.13.0 surface (and matching tip), kino registers 194 MCP tools and 165 CLI commands. The table summarizes core categories — search_tools discovers the exact operation without loading every description.

from kinocut import Client

editor = Client()
matches = editor.search_tools("subtitle")
print(matches["tools"])

Full reference: docs/TOOLS.md

Agent-Safe Workflow

For autonomous agents, the intended path is inspect, edit, verify, then ask a human to review release artifacts:

from kinocut import Client

client = Client()

print(client.inspect("trim"))

result = client.pipeline(
    [
        {"op": "trim", "input": "source.mp4", "start": "00:01:00", "duration": "00:00:45"},
        {"op": "add_text", "text": "Launch clip", "position": "top-center"},
        {"op": "normalize_audio"},
        {"op": "resize", "aspect_ratio": "9:16"},
        {"op": "export", "quality": "high"},
        {"op": "release_checkpoint"},
    ],
    output_path="final-short.mp4",
)

Safety contract:

• Media-producing calls return structured results with output paths.
• High-risk edit paths now run preflight guardrails before FFmpeg execution: filter bounds, merge compatibility, audio mix volume/timing, overlay/watermark/chroma opacity and similarity, animated text timing/overflow, and grid/split-screen mismatch warnings.
• Analysis and discovery calls return structured JSON reports.
• Tool discovery is available through search_tools() and Client.inspect().
• Unexpected keyword errors are converted into actionable MCPVideoError guidance.
• Do not publish agent-generated video without video_quality_check, video_release_checkpoint, and human visual/audio inspection.
• For governed AI-video derivatives (dev tip), require stored identities, active human decision evidence, and a fresh review slot after every salvage or body-swap — never raw FFmpeg workarounds labeled as governed.

FAQ

What is Kinocut?

Kinocut is a free, open-source MCP server, Python library, and kino CLI for AI-agent video editing. It wraps FFmpeg (and optional Hyperframes/Whisper extras) with preflight guardrails, Video Receipts, and quality checkpoints. It was formerly named mcp-video.

How do I install it?

brew install ffmpeg   # or apt install ffmpeg
pip install kinocut
kino doctor
claude mcp add kinocut -- uvx --from kinocut kino

Is it free and local-first?

Yes. Apache-2.0, runs on your machine, no Kinocut account or API key required for the core surface, and media is not uploaded to a Kinocut cloud.

Which agents work with it?

Any MCP-compatible client that can run a local stdio server (Claude Code, Cursor, Windsurf, Cline, and similar). You can also use the Python client or CLI without an agent.

How many tools are there?

Published 1.13.0 documents 194 MCP tools / 165 CLI commands. The development tip matches the published surface.

Was it called mcp-video?

Yes. mcp-video==1.6.4 installs kinocut==1.13.0. Compatibility imports, CLI name, env vars, data dir, resource URIs, and receipt keys remain supported through at least Kinocut 1.8.x.

More answers: docs/faq.md · on-site FAQ: kinocut.dev/#faq

Documentation

• Documentation map
• Product site
• Tool reference
• Python client reference
• CLI reference
• Agent workflow engine
• Video receipts
• Video rescue
• Post-rescue planning
• AI-video review and salvage
• AI-video contracts
• AI-video inspection
• C2PA provenance
• MCPB packaging
• Product roadmap
• Trusted execution layer plan
• Wishlist / 1.8 program parallel plan
• Sound program status
• AI agent discovery guide
• FAQ
• Golden path (first-run proof)
• Public claims (version / counts)
• Golden demo pack
• Changelog
• llms.txt

Testing

Development verification lives in docs/TESTING.md. Keep public-surface, media workflow, and security checks current when changing tool behavior.

Development

git clone https://git.kyanitelabs.tech/KyaniteLabs/kinocut.git
cd kinocut
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v -m "not slow and not hyperframes"

Community

• Contributing
• Code of Conduct
• Governance
• Maintainers
• Security
• Support
• Roadmap
• Changelog
• GitHub issues

Community deploys

Operators who want a public MCP URL without opening home-router ports can study the community Apache-2.0 reference stack that puts Kinocut + Hyperframes behind Tailscale Funnel, Caddy, and Google OAuth (mcp-auth-proxy): hyperframes-selfhost (not affiliated with KyaniteLabs; evaluate security for your threat model).

License

Apache 2.0. See LICENSE.

Built with FFmpeg, Hyperframes, and the Model Context Protocol.

Part of KyaniteLabs

More from KyaniteLabs. Related projects:

• Epoch — time-estimation MCP server (PERT) for AI agents
• DialectOS — Spanish dialect localization MCP server & CLI
• checkyourself — local-first production-readiness checks for AI-built code

→ More at kyanitelabs.tech

If Kinocut is useful to you, star or watch it — it helps other agent builders find it.

Built by Simon Gonzalez De Cruz — available for Forward-Deployed / Applied-AI engineering and contract work via the public profile links above.

What is Kinocut?

Kinocut is a guardrailed video editing MCP server and CLI for AI agents that helps AI agent builders, Claude Code/Cursor users, and local media operators edit, caption, repurpose, and quality-gate video with typed FFmpeg tools.

Who it's for

• Primary: AI agent builders, Claude Code/Cursor users, and local media operators
• Use when you need to edit, caption, repurpose, and quality-gate video with typed FFmpeg tools
• Skip if you need a hosted cloud editor or untyped FFmpeg shell

FAQ

What is Kinocut?

Kinocut is a guardrailed video editing MCP server and CLI for AI agents. It helps AI agent builders, Claude Code/Cursor users, and local media operators edit, caption, repurpose, and quality-gate video with typed FFmpeg tools.

Who should use Kinocut?

AI agent builders, Claude Code/Cursor users, and local media operators.

How is Kinocut different?

Unlike raw FFmpeg scripts or unguarded agent shells, Kinocut validates tools and emits receipts.

Is Kinocut production software?

Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.

Status

• Maintained as of 2026 on the default branch
• Prefer release tags when pinning dependencies
• Report issues on the canonical remote listed above

Agent surface

• Coding agents: read this README first, then repo docs/AGENTS.md if present
• Prefer machine-readable briefs (llms.txt) when the repo ships one
• MCP or skill entrypoints are documented in-repo when applicable

Contributing

Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths.

License

See LICENSE in this repository (or package metadata if license is package-only).