MCP Video 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.

On Hermes: hermes plugins install kinocut, then see the Hermes plugin guide. Other agents: see Install below.

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.

Just say what you want

Give your agent ordinary words. It passes them verbatim to video_direct, reads back the assumptions in one sentence, and asks the plan's single question if present. After you say yes, it calls video_direct_apply(plan=plan, confirm=true). On the default surface both are operations of video_plan_ops. Planning probes the source and never renders or saves files. Hermes already turns voice notes into text; an optional audio_path voice memo uses the existing local transcription path only when no text direction is supplied.

• "Tighten this up and cut the dead air" → remove silence with short sound margins.
• "Make me a 30 second vertical for TikTok with captions" → keep up to the first 30 seconds, resize to 1080×1920, transcribe the final timing, then burn captions.
• "It's too quiet, skip the first 5 seconds" → trim the opening, then normalize to -14 LUFS.

Use kino direct "make it punchier and give me a thumbnail" -i in.mp4 -o out.mp4 to review JSON. Add --apply to execute; an unanswered question keeps it in review. Paths supplied through MCP must be absolute. Intermediate clips, subtitle sidecars, and the thumbnail use deterministic names beside the output. Keep the returned plan JSON in your agent conversation; KinoCut does not store it.

The plan discloses defaults and unknown phrases. Shortening keeps the beginning after cleanup; it does not choose the best moment. Reframing uses a center crop and requires visual review. Muting silences all sound; separate music removal is left unrecognized because it needs model inference. Caption generation and voice memo transcription require the optional local transcription dependency. No speech means caption steps are skipped and receipts identify the actual final video.

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.