# 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 an Apache-2.0 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
- **Last verified publication checkpoint:** 1.16.1 (2026-10-05); consult the official registries for the latest version.
- **Last-updated:** 2026-10-05
- **Published surface (1.16.1):** 203 MCP tools / 177 CLI commands
- **Development checkout:** 1.16.1, 203 MCP tools / 177 CLI commands; matches the published maintenance release.
- **Runtime:** Python 3.11+, FFmpeg on PATH; optional extras for Whisper/upscale/etc.
- **MCP transport:** stdio
- **MCP Registry id:** `tech.kyanitelabs/kinocut`
- **Product site:** https://kinocut.dev/
- **Historical live identity check (2026-09-30):** PyPI, npm and site report 1.15.3; GitHub latest release reports 1.15.0. MCP Registry latest returned HTTP 403, so its current version is unverified.
- **Maintenance publication (2026-10-05):** PyPI/npm and GitHub release report 1.16.1; shim 1.6.16 pins it. The initial publication gate read canonical MCP Registry 1.16.1; later reads timed out. Live site last verified at 1.16.0; prepared 1.16.1 source is not deployed.
- **Release identity checkpoint (2026-10-02):** PyPI/npm/GitHub release/canonical MCP Registry report 1.16.0; shim 1.6.15 metadata pins kinocut1.16.0. The live site was verified at 1.16.0 on 2026-10-05. Fleet work and final owner acceptance remain separate. Canonical website source remains Forgejo.
- **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 --mcp
```

Core FFmpeg edits process local media. An AI host or explicitly configured external
service may receive prompts, results or media; local-first does not guarantee zero
data transfer. Kinocut has no core license fee; hardware, hosting and optional
provider/model costs depend on the chosen workflow.

## 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.16'   # published 1.6.16 shim → kinocut 1.16.1
pip install --force-reinstall --no-deps 'kinocut==1.16.1'
```

Publication checkpoint: 1.6.16 shim → kinocut 1.16.1. Fleet upgrades must verify the installed package and restarted MCP process; see docs/FLEET_UPGRADE.md.

The published compatibility shim is 1.6.16. Compatibility names are preserved;
new integrations should use kinocut, kino and `from kinocut import Client`.

Published identity is maintained in `docs/public_claims.json`.

## Canonical links

- Extended repository agent guide: https://github.com/KyaniteLabs/kinocut/blob/master/docs/llms-full.txt (source companion; website publication is separate)
- Product: https://kinocut.dev/
- Site llms.txt: https://kinocut.dev/llms.txt
- GitHub (canonical code, issues, PRs, CI, and releases): https://github.com/KyaniteLabs/kinocut
- Forgejo (downstream mirror; automated sync cutover pending verification): https://git.kyanitelabs.tech/KyaniteLabs/kinocut
- PyPI: https://pypi.org/project/kinocut/
- MCP Registry: https://registry.modelcontextprotocol.io/v0/servers/tech.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

## Detailed contracts

Use the source-backed references below instead of inferring every schema from this
index. `server.json` is MCP Registry package/transport metadata, not the tool schema.
After connecting, MCP `tools/list` supplies the installed server's tool input schemas;
`search_tools` narrows discovery. The published package and development docs can differ.

- Python API: https://github.com/KyaniteLabs/kinocut/blob/master/docs/PYTHON_CLIENT.md
- Installation: https://github.com/KyaniteLabs/kinocut/blob/master/docs/INSTALL.md
- Quality evidence and capability limits: https://github.com/KyaniteLabs/kinocut/blob/master/docs/QUALITY_EVIDENCE.md
- Project lifecycle: https://github.com/KyaniteLabs/kinocut/blob/master/docs/PROJECTSTORE_LIFECYCLE.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
- Distinguish planning, frame sampling, measured checks and semantic inference; an unavailable backend cannot grant acceptance
- Video Receipts record provenance and review status, not an automatic human sign-off or universal cryptographic signature
- Do not publish without quality/release checks and human visual/audio review

## MCP Registry

Identifier: `tech.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