Skip to main content

🐱 CatCut

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

License: Apache 2.0 Python 3.11+ Windows MCP Kdenlive

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 喵魔人工作室.

Metadata

Release files for catcut 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for catcut 0.1.0
File Size Uploaded Provenance Actions
catcut-0.1.0.tar.gz 265.3 kB Without provenance Details for catcut-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for catcut 0.1.0
File Interpreter ABI Platform Actions
catcut-0.1.0-py3-none-any.whl Python 3 none any Details for catcut-0.1.0-py3-none-any.whl

Total release size: 351.6 kB

Release files / catcut-0.1.0.tar.gz

Download URL catcut-0.1.0.tar.gz
Size 265.3 kB
Tags Source
SHA-256 checksum
How to use checksums
314fc5072d240165d31be3b99d66b1146da26c9b30c17f062240f41e4e9e003d
BLAKE2b-256 checksum
How to use checksums
408af854cab560f573b72f0ed47c01fe76899052b4d65fbf8e60bccc6dd51c68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.13 {"installer":{"name":"uv","version":"0.11.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / catcut-0.1.0-py3-none-any.whl

Download URL catcut-0.1.0-py3-none-any.whl
Size 86.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3aad3f3776a228b60498bbb7a364dffe5e13e3cc6f4503f0103abe553a1c0231
BLAKE2b-256 checksum
How to use checksums
6d2d05ac0c0f67ef9a698da9a46c5feafb56aa28c009597a139e921a010d46cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.13 {"installer":{"name":"uv","version":"0.11.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for catcut 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page