kinocut
A local, guardrailed video-editing MCP server (206 tools, 18 listed by default) that lets an AI agent inspect, edit, grade, and QC real media with FFmpeg — safely, on your machine, with no uploads.
Probe & diagnose:
video_info,video_doctor, read metadata and detailed stream info before editing.Core edits:
video_trim,video_merge,video_add_text,video_add_audio(mix/replace, fades, gain, duration policy),video_extract_frame, and one-call verticalvideo_shorts(trim + caption + resize + export).Edit family (
video_edit_ops): crop, resize, rotate, speed, fade, overlay, watermark, chroma/luma/shape masks, composite layers, split-screen, subtitles, convert, export frames, HLS segmenting, storyboards, batch jobs, cleanup, quality comparison.Effects family (
video_effects_ops): filters (glow, vignette, noise, scanlines, chromatic aberration), glitch set (VHS, datamosh, RGB shift, screen tearing, etc.), transitions, layout grids/PiP, animated text and motion-graphics counters.Audio family (
audio_ops): compose/sequence/synthesize, presets and effects, mixing, ducking, spatial audio, sound-plan validation, loudness and ASR QA.AI family (
video_ai_ops): transcription, scene detection, silence removal, upscaling, stem separation, color grade, quality/design checks, acceptance verdicts, release checkpoints, salvage.Image/still family (
image_ops): product analysis, color extraction, palette generation, still match/grade, gating and packaging.Inspection & release (
video_qc_ops): preflight, publish gate, capabilities, cost ledger, review packages and decisions, temporal inspection, text-layout validation, benchmarks.Planning (
video_plan_ops): natural-languagevideo_direct(plan, then apply on confirm), intents, cutfiles, timelines/OTIO import-export, workflow plan/render/validate, rescue plans, repurposing, B-roll and hook proposals, translation.Platform (
platform_ops): Hyperframes and Revideo composition/render/preview/TTS, Shorts packaging, review and planning.Discovery:
list_operationsanddescribe_operationexpose the full catalog and per-op schemas on demand to keep the default tool list small.Guardrails: new files unless
overwriteis explicit, validation before FFmpeg runs, structured JSON results, deterministic sidecar names, and no network calls unless opted in.
Provides a high-level API for video editing by wrapping FFmpeg, enabling tools for trimming, merging, adding text or audio overlays, format conversion, and metadata extraction.
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 --mcpOr 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 doctorkino 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.
Related MCP server: video-editor
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.
Mode | Set with | Tools listed | What's in it |
Default | nothing | 18 | 8 hot-path tools, 8 operation families, |
Profile |
| varies | One job's tools by name, plus the families |
Everything |
| 206 | Every tool by its own name |
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_cardwrites 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.mp4writes 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
Job | Where to start |
Trim, merge, caption, resize, convert, overlay, crop, speed | Hot path and |
One-call vertical shorts from chosen ranges |
|
Podcast or stream to Shorts, Reels and TikTok packages | |
Loudness, quality and release gates |
|
Multi-step jobs from one JSON spec, resumable | |
Diagnose and repair a damaged clip without changing its story | |
Review and salvage AI-generated video | |
A two-cam edit from one stitched 360 MP4 | |
Cut a product out of a still or turntable video | |
Match and grade a set of stills to a hero image | |
Mix, duck, master and check speech audio | |
Code-driven motion graphics | Hyperframes and Revideo tools, see tool reference |
Signed provenance on final exports |
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-darkReferences: 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
Version | Surface | |
Published on PyPI, npm and the MCP Registry | 2.0.1 (2026-11-10) | 206 MCP tools with |
Development (unreleased #458) | 2.0.1 + | 208 MCP tools with |
Compatibility package |
| Installs |
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
Source | |
MCP Registry | |
PyPI | |
Site | |
Runs on | macOS, Linux, Windows, with Python 3.11+ and FFmpeg |
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 --mcpkino 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 honestnormalize_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-imageswith 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 doctorPython-version floor with a visible install hint (#459), shipped in 1.15.0.@betsmayank: the first merged external fix, so Hyperframes
initno 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_stillruntime 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.
Available Tools
18 toolsaudio_opsAudio operations (mix, synthesize, presets, sound pipeline, QC)BDestructive
Run one audio operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
describe_operationDescribe one operationARead-onlyIdempotent
Return one operation's full inputSchema, the family tool that dispatches it, and its kino CLI route when one exists.
Inputs: operation (required). Returns: object
image_opsImage and still operations (colors, palettes, grade, gate, packaging)BDestructive
Run one image/still operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
list_operationsList family operationsARead-onlyIdempotent
List operations: families with member counts, and each operation's family, verb, required parameters and side-effect annotations.
Inputs: query, family. Returns: object
platform_opsPlatform operations (hyperframes, revideo, shorts packaging)BDestructive
Run one platform operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_add_audioAdd or mix video audioADestructive
Add, replace, or mix an audio track into a video and render a new file; the sources are only read. Returns JSON {success, output_path}.
Inputs: audio_path (required), video_path (required), mix, volume, +6 more. Returns: object
video_add_textBDestructive
Burn one text element (title, caption, watermark) into a video. Returns JSON {success, output_path}.
Inputs: text (required), input_path (required), crf, font, +9 more. Returns: object
video_ai_opsAI operations (transcription, scene detect, upscale, verdicts, quality)ADestructive
Run one AI operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_doctorARead-onlyIdempotent
Return a read-only JSON readiness verdict for the next video job.
Inputs: no named parameters. Returns: object
video_edit_opsEdit operations (trim, merge, text, convert, export, metadata, batch)CDestructive
Run one edit operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_effects_opsEffect operations (filters, transitions, glitch, motion graphics)ADestructive
Run one effect operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_extract_frameADestructive
Extract one frame as an image. Without a timestamp, picks a smart thumbnail (fallback: 10% into the clip); pass 0 for the first frame.
Inputs: input_path (required), overwrite, timestamp, output_path. Returns: object
video_infoARead-onlyIdempotent
Probe a video file for metadata. Returns JSON {success, info:{duration, resolution, codec, fps, size, ...}}. Use before any edit to learn the source's dimensions and length.
Inputs: input_path (required), exact. Returns: object
video_mergeMerge video clipsBDestructive
Concatenate two or more video clips, in order, into one rendered file. Returns JSON {success, output_path}.
Inputs: clips (required), review, overwrite, transition, +3 more. Returns: object
video_plan_opsPlanning operations (intent, cutfiles, timelines, rescue, workflow, repurpose)CDestructive
Run one planning operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_qc_opsInspection and release operations (doctor, preflight, guardrails, review, publish)BDestructive
Run one inspection/release operation by name; params holds its arguments. Required arguments: list_operations; full schema: describe_operation.
Inputs: operation (required), params, overwrite. Returns: object
video_shortsBDestructive
Trim, caption, make vertical, and export selected segments in one call.
Inputs: segments (required), input_path (required), style, review, +2 more. Returns: object
video_trimBDestructive
Cut a segment out of a video by start time and duration or end. Returns JSON {success, output_path} pointing at the rendered clip.
Inputs: input_path (required), end, start, review, +4 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Eight dispatcher tools (video_edit_ops, video_effects_ops, video_qc_ops, video_plan_ops, video_ai_ops, audio_ops, image_ops, platform_ops) share essentially identical descriptions and signatures, differing only by family name, so the agent must guess which family holds the operation it needs. There is also overlap between direct tools (video_trim, video_merge, video_add_text, video_add_audio) and the edit/effects/audio dispatchers, which plausibly contain the same operations.
Most names use snake_case with a video_ prefix, but the set mixes two conventions: concrete verb_noun tools (video_add_text, video_trim, video_extract_frame) and generic family dispatchers ending in _ops. The two meta-tools list_operations and describe_operation drop the prefix entirely, adding a third minor deviation.
At 18 tools this sits in the borderline-heavy band, and the count is inflated by eight near-duplicate dispatchers that provide little surface-level differentiation. The dispatcher pattern does cap growth as operations expand, so the total is defensible but not tight.
The surface covers the core video lifecycle — probe, trim, merge, text, audio, frame extraction, shorts assembly, readiness check — plus dispatchers for edit, effects, QC, planning, AI, image and platform operations. Coverage is broad; the main weakness is that most capability is hidden behind an undisclosed operation catalog rather than directly discoverable tools.
Maintenance
Related MCP Connectors
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
FFmpeg Micro - The FFmpeg Api - www.ffmpeg-micro.com Transcode videos from n8n or Make using FFmpeg in the cloud. MCP Server: https://github.com/ffmpeg-micro/ffmpeg-micro-mcp/
FFmpeg processing for video, audio and images via MCP with OAuth and shared account allowance.
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables comprehensive video and audio processing using FFmpeg, supporting tasks like metadata extraction, clipping, scaling, and adding transitions or overlays. It provides a high-performance interface for building media processing microservices via FastMCP.1212-
- AlicenseNot gradedqualityDmaintenanceAn MCP server for programmatic video editing using ffmpeg, enabling draft creation and refinement via natural language.15 npmISC
- AlicenseAqualityDmaintenanceEnables LLMs to perform FFmpeg operations like clipping, merging, extracting audio, adding subtitles, and transcoding videos via a set of tools exposed as an MCP server.58MIT
- AlicenseAqualityDmaintenanceProvides 30+ FFmpeg video and audio editing tools via MCP, enabling AI assistants to perform operations like trimming, transcoding, overlays, and composition directly.274MIT