Kinocut is a local, guardrailed MCP video-editing server that lets an AI agent inspect, edit, render, and quality-check video while writing new files and returning structured results.
Probe video metadata, including exact frame counts and frame-rate details.
Trim clips by start time plus duration or end time, with optional frame-accurate seeking.
Merge multiple clips into one video, optionally with crossfade transitions.
Overlay one or many text elements with positioning, styling, shadows, and timing; validate text layouts before rendering.
Add, replace, or mix audio tracks with volume, fades, offsets, and duration policies.
Resize videos or change aspect ratio; convert formats/codecs such as MP4, WebM, GIF, MOV, HEVC, AV1, and ProRes.
Change playback speed for slow-motion or fast-forward effects.
Extract frames at explicit timestamps or via automatic sampling.
Create one-call vertical shorts by trimming, captioning, resizing, and exporting selected segments.
Run visual/audio quality checks and optionally treat warnings as failures.
Scaffold video projects, search available tools, and diagnose Kinocut or Hyperframes readiness.
Assemble review packages with publish-gate verdicts and inspect rescue/workflow receipts with integrity checks.
The full catalog exposes many more operations through tool families, including effects, AI-video review, image operations, QC, workflows, platform operations, and C2PA provenance.
Safe by default: no overwrites unless explicitly allowed, validation before FFmpeg runs, local-only processing, and no unrequested network calls.
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.
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.0 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.0", "kino", "--mcp"]
}
}
}Or install the package and check your machine:
pip install kinocut==2.0.0
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
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.
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.
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
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.
Version | Surface | |
Published on PyPI, npm and the MCP Registry | 2.0.0 (2026-11-10) | 206 MCP tools with |
Compatibility package |
| Installs |
Install from PyPI: the published 2.0.0 package includes the optional object-matte extra
(kinocut[object-matte]==2.0.0), which adds no new MCP tool.
Full notes: CHANGELOG.md · published 2.0.0 on PyPI
Source | |
MCP Registry | |
PyPI | |
Site | |
Runs on | macOS, Linux, Windows, with Python 3.11+ and FFmpeg |
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.
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.0. Necesitas FFmpeg en el PATH.
pip install kinocut==2.0.0
kino doctor
claude mcp add kinocut -- uvx --from kinocut==2.0.0 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.
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.
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).
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.
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
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
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 operations: families with member counts, and each operation's family, verb, required parameters and side-effect annotations.
Inputs: query, family. Returns: object
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
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
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
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
Return a read-only JSON readiness verdict for the next video job.
Inputs: no named parameters. Returns: object
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
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
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
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
Concatenate two or more video clips, in order, into one rendered file. Returns JSON {success, output_path}.
Inputs: clips (required), overwrite, transition, output_path, +2 more. Returns: object
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
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
Trim, caption, make vertical, and export selected segments in one call.
Inputs: segments (required), input_path (required), style, overwrite, +1 more. Returns: object
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, accurate, +3 more. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
The direct tools (video_trim, video_merge, video_add_text, video_extract_frame) are recognizable, but the eight generic dispatchers overlap heavily with them and with each other: it is unclear whether trimming belongs to video_edit_ops, whether captions/text belong to video_effects_ops or video_ai_ops, or how video_info differs from video_qc_ops. Only runtime calls to list_operations/describe_operation resolve which family owns an operation, so an agent cannot reliably pick a tool up front.
Names are all snake_case and readable, but two different schemes are mixed: direct tools use a verb_noun pattern (video_trim, video_extract_frame) while the family tools use a noun_ops dispatcher pattern (audio_ops, platform_ops). The 'video_' prefix is applied to most but dropped on audio_ops, image_ops and platform_ops, adding inconsistency.
18 tools sits in the heavy/borderline range, and eight of them are generic op dispatchers whose real surface is hidden and potentially very large. The meta-layer (list_operations + describe_operation + 8 dispatchers) consumes over half the tool surface to route to operations that the direct tools also partly cover.
Core video workflows are covered end to end: probe, trim, merge, audio, text, frame extraction, shorts, plus families for effects, AI, images, QC and planning. Some gaps remain — no visible job status/cleanup or file-listing operation, and undo/history is absent — but these are largely workaroundable or possibly inside platform_ops.
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.
