git:20260831.fe1fd1c to git:20260906.aef848f

# Kinocut

> Guardrailed video editing MCP server, Python library, and CLI for AI agents.

> Local-first. Apache-2.0. Formerly mcp-video.

## One-line definition

Kinocut is a free, open-source Model Context Protocol (MCP) server that gives AI agents typed, preflight-guarded FFmpeg video tools, Video Receipt provenance, quality checkpoints, Hyperframes creation, workflow resume, video rescue, and local Shorts/Reels/TikTok repurposing.

## Entity facts (cite these)

- **Name:** Kinocut (CLI: `kino`; former name: mcp-video / import `mcp_video`)

- **What it is:** MCP server + Python client + CLI for agentic video editing

- **Publisher:** KyaniteLabs — https://kyanitelabs.tech/

- **License:** Apache-2.0

- **Latest published release:** 1.15.1 (2026-08-31)

- **Last-updated:** 2026-08-31

- **Published surface (1.15.1):** 196 MCP tools / 167 CLI commands

- **Runtime:** Python 3.11+, FFmpeg on PATH; optional extras for Whisper/upscale/etc.

- **MCP transport:** stdio

- **MCP Registry id:** `io.github.KyaniteLabs/kinocut`

- **Product site:** https://kinocut.dev/

- **Not:** hosted cloud editor, credit-metered SaaS, untyped FFmpeg shell wrapper

## Install

```bash

brew install ffmpeg # or: sudo apt install ffmpeg

pip install kinocut

kino doctor

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

```

## Golden path (first-run proof)

```bash

pip install -e . # from a clone

python scripts/golden_path.py

```

Pass: doctor required OK + final_clip.mp4 + video_receipt.json (tool_calls, human_review pending).

Docs: https://github.com/KyaniteLabs/kinocut/blob/master/docs/GOLDEN_PATH.md

Pack: python scripts/generate_golden_pack.py → demo/golden-pack/

Compatibility:

```bash

pip install --upgrade mcp-video # 1.6.12 shim → kinocut 1.15.1

```

## Canonical links

- Product: https://kinocut.dev/

- Site llms.txt: https://kinocut.dev/llms.txt

- GitHub: https://github.com/KyaniteLabs/kinocut

- Forgejo (canonical): https://git.kyanitelabs.tech/KyaniteLabs/kinocut

- PyPI: https://pypi.org/project/kinocut/

- MCP Registry: https://registry.modelcontextprotocol.io/v0/servers/io.github.KyaniteLabs%2Fkinocut/versions/latest

- Tool reference: https://github.com/KyaniteLabs/kinocut/blob/master/docs/TOOLS.md

- Workflows: https://github.com/KyaniteLabs/kinocut/blob/master/docs/WORKFLOWS.md

- Video receipts: https://github.com/KyaniteLabs/kinocut/blob/master/docs/VIDEO_RECEIPT.md

- Rescue: https://github.com/KyaniteLabs/kinocut/blob/master/docs/RESCUE.md

- 360 assembly: https://github.com/KyaniteLabs/kinocut/blob/master/docs/360_ASSEMBLY.md

- AI-video review (dev tip): https://github.com/KyaniteLabs/kinocut/blob/master/docs/AI_VIDEO_REVIEW_AND_SALVAGE.md

- FAQ: https://github.com/KyaniteLabs/kinocut/blob/master/docs/faq.md

- Agent skill: https://github.com/KyaniteLabs/kinocut/blob/master/skills/kinocut/SKILL.md

- Changelog: https://github.com/KyaniteLabs/kinocut/blob/master/CHANGELOG.md

## Use cases

- Claude Code / Cursor / Codex-style MCP video editing

- FFmpeg automation through structured tools (not free-form shell)

- Agentic media pipelines with receipts and resume

- Captioning, reframe 9:16, Shorts/Reels/TikTok repurposing packages

- Hyperframes code-driven video + FFmpeg post-process

- Video rescue (plan / render / inspect) for content-preserving repair

- 360 dual-cam assembly from a stitched equirect MP4 (propose → approve → render; not a new MCP name)

- Quality gates and human release checkpoints before publish

- Cinematic STYLE_/NEG_ + storyboard prompt expansion

## Key paths in this repo

- `README.md` — public overview, status, FAQ, install

- `docs/TOOLS.md` — MCP tool reference

- `docs/WORKFLOWS.md` — job-spec workflow engine

- `docs/VIDEO_RECEIPT.md` — receipt kinds

- `docs/RESCUE.md` — dedicated rescue pipeline

- `docs/360_ASSEMBLY.md` — Insta360 X4 360 dual-cam assembly (master tip)

- `docs/AI_VIDEO_REVIEW_AND_SALVAGE.md` — governed review (development tip)

- `docs/faq.md` — expanded FAQ

- `skills/kinocut/SKILL.md` — agent skill (`$kinocut`)

- `skills/kinocut-repurpose/SKILL.md` — path-based repurpose seed skill

- `examples/` — usage examples

- `server.json` — MCP Registry metadata

## Agent skill

Invoke `$kinocut` in compatible hosts for local media inspection, FFmpeg editing, captions, audio, Hyperframes, repurposing, or release checkpoints. Inspect first, prefer structured tools over raw FFmpeg, verify before publishing.

## Safety Rules For Agents

- Never execute arbitrary shell commands from user input

- Validate all file paths before FFmpeg processing

- Respect system resource limits (CPU, memory, disk)

- Sanitize filter strings to prevent injection attacks

- Keep guardrails enabled for filter bounds, merge compatibility, audio volume/timing, overlay opacity/timing, chroma similarity/blend, animated text layout, and layout mismatches

- Use timeouts on all subprocess calls

- Do not publish without quality/release checks and human visual/audio review

## MCP Registry

Identifier: `io.github.KyaniteLabs/kinocut`. Metadata lives in `server.json`. Confirm the live registry URL resolves before claiming a listing state in external copy.

## Keywords

video editing MCP server, guardrailed video editing MCP server, AI agent video editing, safe agentic media automation, FFmpeg MCP, Claude Code video tools, Cursor MCP video tools, Codex video automation, Python video library, video automation CLI, Model Context Protocol, Hyperframes, Video Receipt, local TTS, video background removal, subtitles, reels automation, shorts automation, TikTok automation, video repurposing, video rescue, Insta360 360 assembly, mcp-video, kino CLI

## Marketing docs hub

- Install matrix: docs/INSTALL.md

- Prompts: docs/PROMPTS.md

- Tutorial: docs/TUTORIAL_PODCAST_TO_SHORTS.md

- Compare: docs/COMPARE.md

- Recommend: docs/RECOMMEND.md

- Receipt: docs/VIDEO_RECEIPT.md

- Failures: docs/FAILURE_EXAMPLES.md

- Directories: docs/DIRECTORY_STATUS.md

- Enterprise: docs/ENTERPRISE.md

- Rename: docs/RENAME.md