Skip to main content
Glama

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.

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, list_operations, describe_operation

Profile

KINOCUT_TOOLS=profile:editor (19 profiles)

varies

One job's tools by name, plus the families

Everything

KINOCUT_TOOLS=all

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_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

Job

Where to start

Trim, merge, caption, resize, convert, overlay, crop, speed

Hot path and video_edit_ops

One-call vertical shorts from chosen ranges

video_shorts

Podcast or stream to Shorts, Reels and TikTok packages

Tutorial, stream-to-shorts

Loudness, quality and release gates

video_qc_ops, quality evidence

Multi-step jobs from one JSON spec, resumable

Workflow engine

Diagnose and repair a damaged clip without changing its story

Video rescue

Review and salvage AI-generated video

AI-video review

A two-cam edit from one stitched 360 MP4

360 assembly

Cut a product out of a still or turntable video

Product matte

Match and grade a set of stills to a hero image

Still plates

Mix, duck, master and check speech audio

Audio mixing, sound mixes

Code-driven motion graphics

Hyperframes and Revideo tools, see tool reference

Signed provenance on final exports

C2PA

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

Version

Surface

Published on PyPI, npm and the MCP Registry

2.0.1 (2026-11-10)

206 MCP tools with KINOCUT_TOOLS=all, 18 by default, 177 CLI commands

Development (unreleased #458)

2.0.1 + video_direct

208 MCP tools with KINOCUT_TOOLS=all, 18 by default, 178 CLI commands

Compatibility package

mcp-video==1.6.22

Installs kinocut==2.0.1 for anyone still on the old name

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

GitHub (canonical) · Forgejo (downstream mirror)

MCP Registry

tech.kyanitelabs/kinocut

PyPI

kinocut

Site

kinocut.dev

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

Available Tools

18 tools
audio_opsAudio operations (mix, synthesize, presets, sound pipeline, QC)B
Destructive

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 operationA
Read-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)B
Destructive

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 operationsA
Read-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)B
Destructive

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 audioA
Destructive

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_textB
Destructive

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)A
Destructive

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_doctorA
Read-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)C
Destructive

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)A
Destructive

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_frameA
Destructive

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_infoA
Read-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 clipsB
Destructive

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)C
Destructive

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)B
Destructive

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_shortsB
Destructive

Trim, caption, make vertical, and export selected segments in one call.

Inputs: segments (required), input_path (required), style, review, +2 more. Returns: object

video_trimB
Destructive

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

    B3.1/5.0

    Scored across 18 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers