catcut 0.1.0

Veteran-level video editing automation for Kdenlive via MCP — Windows, local, offline, free.

🐱 CatCut

Veteran-level video editing automation for Kdenlive — driven by Large Language Models via MCP.

Built with love by 喵魔人工作室 / Meow Demon Studio. Local. Offline. Free. Forever.

---

What is CatCut?

CatCut is an MCP (Model Context Protocol) server that lets a Large Language Model — Claude, GPT, Gemini, or any MCP-compatible client — operate Kdenlive at the level of a 15-year veteran editor.

Drop a folder of raw footage, an audio track, and an SRT file. Ask: "Cut this interview down to 5 minutes, remove filler words, sync subtitles, add gentle background music, render to YouTube preset." CatCut writes a clean .kdenlive project and renders the final cut — fully offline, on your own machine.

CatCut targets four professional editing verticals:

Vertical	Examples
Interview / Podcast	One-on-one talks, panel discussions, podcast video versions
YouTube Knowledge	Tutorials, explainers, course videos, talking-head content
Short-form Social	Reels, Shorts, TikTok — auto-reframe to 9:16 with subject tracking
Event Records	Wedding highlights, conferences, workshops, recitals

CatCut does not target ads/brand films or documentaries — those need creative direction that LLMs cannot reliably replace.

---

Why CatCut?

• 🆓 Truly free, truly local. No accounts, no API keys, no cloud rendering. Your footage stays on your drive.
• 🏆 Veteran-grade defaults. Backed by 1000+ project decisions encoded as YAML Playbooks. Not a toy.
• 🧱 LLM-friendly architecture. 4-layer tool design (XML primitives → Editor Actions → Semantic Operations → Playbook DSL) cuts token cost by ~80% vs. naive XML poking.
• 🔌 Open standard. Built on Anthropic's Model Context Protocol. Works with Claude Desktop, Claude Code, Cline, Continue, custom clients.
• 📜 Apache 2.0. Fork it, ship it, learn from it. No strings.

---

Status

🚀 v0.1.0 (Alpha). Four production verticals ship with end-to-end Playbooks: interview, short-form (9:16), wedding (two-camera sync), event highlights. Docs site live at nice923boss.github.io/CatCut.

See docs/ROADMAP.md for the milestone breakdown and CHANGELOG.md for what shipped in 0.1.0.

---

Quick start (preview)

# 1. Install prerequisites
winget install astral-sh.uv
winget install KDE.Kdenlive

# 2. Install CatCut
uv tool install catcut

# 3. Wire it into your MCP client (Claude Desktop / Claude Code / etc.)
catcut config show-mcp
# ... copy the JSON snippet into your client's config ...

# 4. Ask your LLM
> "Open the folder C:/footage/2026-05-13-interview, find the cleanest 3 minutes,
>  add the SRT next to it, render to YouTube 1080p."

See docs/setup.md for the full setup walkthrough, including Claude Code and HoloTeam integration.

---

Architecture (one-screen overview)

┌────────────────────────────────────────────────────────────┐
│  LLM client (Claude Code / Claude Desktop / HoloTeam / …)  │
└────────────────────────────┬───────────────────────────────┘
                             │ MCP (stdio)
┌────────────────────────────▼───────────────────────────────┐
│  catcut-mcp server                                         │
│                                                            │
│  L3  Playbook DSL  ← YAML pipelines (interview, vlog, …)   │
│  L2  Semantic ops  ← cut_silences, sync_subtitles, …       │
│  L1  Editor actions ← add_clip, add_track, add_effect, …   │
│  L0  XML primitives ← producer, playlist, entry, filter    │
└────────────────────────────┬───────────────────────────────┘
                             │ writes .kdenlive XML
                             │ calls kdenlive_render.exe
┌────────────────────────────▼───────────────────────────────┐
│  Kdenlive (GPL) — used at arm's length, never linked       │
└────────────────────────────────────────────────────────────┘

Full architecture: docs/architecture.md.

---

Playbooks: where the craft lives

A Playbook is a YAML file that encodes a veteran editor's standard operating procedure for a specific kind of video. They're declarative, version-controlled, and forkable.

# examples/playbooks/interview_5min.yaml
name: "Interview → 5-minute YouTube cut"
inputs:
  camera:   { kind: video, role: A-roll }
  mic:      { kind: audio, role: clean-dialog }
  srt:      { kind: subtitle, optional: true }
target:
  duration_s: 300
  preset: youtube_1080p
steps:
  - cut_silences: { threshold_db: -40, min_silence_ms: 600, keep_padding_ms: 120 }
  - remove_fillers: { lang: zh-TW, words: [那個, 嗯, 啊] }
  - sync_subtitles: { source: srt, fallback: whisper }
  - apply_loudness_target: { lufs: -14, true_peak_dbtp: -1 }
  - color_grade: { profile: interview_warm }
  - add_lower_third: { template: simple_white, hold_s: 4 }
  - render: { preset: $target.preset }

The community is invited to contribute Playbooks for niches we don't cover. See docs/playbooks.md.

---

Contributing

CatCut is built in the open. PRs welcome — start with CONTRIBUTING.md and the good first issue label.

Areas we'd love help with:

• Additional Playbooks for niche workflows
• Localization (i18n) for prompts, docs, defaults
• Performance profiling on lower-end Windows hardware
• Bug reports with reproducible .kdenlive files

---

Legal & licensing

• CatCut itself is Apache 2.0 — see LICENSE and NOTICE.
• CatCut never statically links Kdenlive, MLT, or FFmpeg. It writes XML files and invokes binaries via subprocess. The user installs Kdenlive separately under its own GPL license.
• See docs/legal/THIRD_PARTY.md for the full attribution table.

---

Acknowledgements

CatCut stands on the shoulders of:

• Kdenlive by KDE — the world's best free, open-source video editor.
• MLT Framework by Meltytech / Dan Dennedy — the rendering engine behind the magic.
• Anthropic — for inventing MCP and building Claude Code.
• The whisper.cpp / ONNX Runtime / sherpa-onnx communities — for making local AI inference possible on consumer hardware.

---

Made with 🐱 in Taiwan by 喵魔人工作室.