Kinocut README

Kinocut

Your agent edits the video. You approve the cut.
A local, guardrailed video-editing MCP server, Python client and kino CLI. Free, Apache-2.0. Formerly mcp-video.

You tell your agent, "cut the best 45 seconds of this interview into a captioned vertical short." Without help, the agent guesses FFmpeg flags, overwrites your source, and hands back a file it never looked at.

Kinocut gives the agent typed tools instead. Every edit is checked before FFmpeg runs, writes to a new file unless you allow an overwrite, and returns a structured result the agent can inspect. Quality gates catch black frames, silence and bad loudness before you see the cut, and a Video Receipt records what was asked, what ran and what changed.

Everything runs on your machine. No account, no upload, no credits.

Install

Kinocut needs FFmpeg on your PATH (brew install ffmpeg, sudo apt install ffmpeg, or winget install ffmpeg).

Add it to Claude Code:

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

Or to any MCP client that reads a JSON config (Claude Desktop, Cursor, Windsurf, Zed):

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

Or install the package and check your machine:

pip install kinocut==2.0.1
kino doctor

kino doctor lists which features are ready and what each missing one needs. Optional features install as extras; the install matrix lists them all.

For Claude Desktop extension installs, python3 scripts/build-mcpb.py builds a local .mcpb from mcpb/. It is unsigned and labeled user-configured-local-access: it launches your own Python environment, still needs Node and FFmpeg, and is not a sandbox. See docs/MCPB.md.

What your agent sees

An agent pays for every tool description it reads, on every turn. Kinocut keeps the default list small and puts the rest one call away.

The hot path is video_info, video_trim, video_merge, video_add_text, video_add_audio, video_extract_frame, video_shorts and video_doctor.

The eight families (video_edit_ops, video_effects_ops, audio_ops, video_ai_ops, image_ops, video_qc_ops, video_plan_ops, platform_ops) reach every other operation in the catalog. The agent calls list_operations to see what a family can do and describe_operation to fetch one operation's full schema. Family dispatch runs the same code as the named tool, so the results are identical. See MCP operation families.

The 18-tool default listing is about 22 KB of JSON. The full catalog is about 178 KB.

Review a cut where you already are

• Hermes Desktop chat. video_review_card writes an HTML card with a contact sheet, duration, resolution and codec, and three buttons: Approve & export, Dig in, Try another range. An opt-in Desktop plugin shows live render progress in the status bar and a "Kinocut renders" pane. See the Hermes plugin.
• A paired Hermes Gadget TV. The plugin skill can put the cut on the TV and map the remote's Approve and Reject to Approve & export and Try another range. The TV needs a URL it can fetch; Kinocut does not serve one.
• Anywhere else. kino release-checkpoint clip.mp4 writes a thumbnail, a storyboard and a pass/fail quality report next to the clip.

What it can do

The same engine sits behind all three interfaces:

from kinocut import Client

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

kino info interview.mp4
kino trim interview.mp4 -s 00:02:15 -d 45
kino release-checkpoint clip.mp4 --profile ui-capture-dark

References: MCP tools · Python client · CLI · Video Receipts · agent discovery · all docs · llms.txt

Safe by default

• New files, not overwrites. Writing over an existing file needs an explicit overwrite.
• Checked before FFmpeg runs. Filter ranges, merge compatibility, mix levels, overlay opacity and text timing are validated first, and errors end with the exact retry call.
• No network calls you didn't ask for. Optional model features are off until you turn them on; see vision and network controls.
• Nothing gets posted. Kinocut renders and packages. Publishing stays with you.

What it won't do: Kinocut renders real media only. No generation adapter exists for text-to-video or paid image generation, and caption speech uses local stock speech (eSpeak NG), not a neural voice. The kinocut_sound program ships its thin S12 join; its benchmark is 64 synthetic clips, not a full episode and not human listening approval.

Releases

Install from PyPI: the published 2.0.1 package includes the optional object-matte extra (kinocut[object-matte]==2.0.1), which adds no new MCP tool.

Full notes: CHANGELOG.md · published 2.0.1 on PyPI

Coming from mcp-video

The project was called mcp-video until 2026-07-10. The old import (mcp_video), command (mcp-video), MCP_VIDEO_* variables and ~/.mcp-video data directory still work. New setups should use kinocut, from kinocut import Client and kino. See the rename notes.

En español

Kinocut es un servidor MCP local para que tu agente de IA edite video con barreras de seguridad: recorta, une, subtitula, mezcla audio, crea Shorts y revisa la calidad antes de entregarte el corte. Nunca sobrescribe tus archivos sin permiso y no sube nada a la nube. La versión publicada es 2.0.1. Necesitas FFmpeg en el PATH.

pip install kinocut==2.0.1
kino doctor
claude mcp add kinocut -- uvx --from kinocut==2.0.1 kino --mcp

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

Develop

git clone https://github.com/KyaniteLabs/kinocut.git
cd kinocut
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q -m "not slow and not hyperframes"

Contributing · Testing · Security · Support · Governance · Maintainers · Code of Conduct · Roadmap

Want a public MCP URL without opening router ports? hyperframes-selfhost is a community Apache-2.0 reference stack (Tailscale Funnel, Caddy, Google OAuth). It is not affiliated with KyaniteLabs; review it against your own threat model.

Contributors

Kinocut is better because people outside the core team sent code and sharp bug reports. A report with reproduction steps and a real traceback is a contribution, and every one is credited here and in the CHANGELOG.

• @guillaume-hestia-projekt: 19 reproducible bug reports from building on kinocut.Client (#546–#578), plus fixes: FFmpeg children no longer inherit stdin (#559), composite-layers canvas fps (#558) and honest normalize_audio (#569), shipped in 1.15.3. Their crop, trim, noise-floor, one-pass mixing and timed-layer patches were adapted into 1.16.0 (#586).
• @WohaibHasan: absolute trim-end handling (#493), Windows drive preservation (#496) and portable UTF-8 CLI test capture (#498).
• @Beritwu: frame-exact create-from-images with rational frame rates and list input (#616, shipped in 1.16.2), and the opt-in exact probe (#599, shipped in 1.16.5).
• @cnw-L: Windows drive paths survive the lavfi movie= filter (#532), shipped in 1.15.3.
• @gerardoscaglia-creator: a Windows MCP-mode investigation (#445) that exposed both diagnostics gaps fixed in 1.15.0, and the portable file-locking fix (#446) that shipped with them.
• @pedropaav-art: Windows filter-option path escaping (#458), shipped in 1.15.0.
• @linhaixin45-cmyk: a kino doctor Python-version floor with a visible install hint (#459), shipped in 1.15.0.
• @betsmayank: the first merged external fix, so Hyperframes init no longer hangs under MCP without a TTY (#361).
• @AnttonioAzevedo: caught silence removal writing corrupt MP4s (#467, fixed in #506).
• @Mimatovitch: reported the macOS process-cleanup regression (#594), fixed in 1.16.1 (#596).
• @Zoroassistant23: investigated #594 and proposed a patch with macOS checks and a regression test (#595).
• @austinwmson and @ismailkattakath: reports that closed real gaps, remotion_still runtime props (#306) and the self-host reference stack (#432).
• @Dodothereal and @OyaAIProd (account since deleted): early external PRs, including ASS PlayRes for vertical burns (#378).

License

Apache 2.0. See LICENSE. Built on FFmpeg, Hyperframes and the Model Context Protocol.

Made by Simon Gonzalez De Cruz at KyaniteLabs. Sibling projects: Epoch (time estimates for agents), DialectOS (Spanish dialect localization) and checkyourself (production-readiness checks for AI-built code). If Kinocut saved you editing hours: ko-fi.com/kyanitelabs.