kdenlive-editing-mcp

Scripted video editing with Kdenlive 26.08.1 / MLT 7.41.0, driven from Python, with an MCP server on top. Built because a .kdenlive file is an undocumented internal serialisation and the toolchain around it fails silently — wrong frame rate, missing audio, clips in the wrong place — rather than with an error.

Pointed at a folder of footage, it writes a project you can open and start cutting, then proves the result is right by rendering frames back out of the finished timeline and comparing them against the source.

Verified against Kdenlive 26.08.1, MLT 7.41.0, document version 1.1. The project format is not a public API and changes between releases; treat that as a version pin.

Layout

Related MCP server: mcp-kdenlive

Usage

scripts/stringout.py raw-videos/ -s 1.5 -o assembly.kdenlive
scripts/stringout.py raw-videos/ --transcode proxies/ --verify

A stringout is every take in order, trimmed to a glance — a starting point to cut against rather than a finished edit. Clips land on V1 with their audio on A1, grouped so they move together; the bin keeps every clip at full length, so any slice can be pulled longer by hand afterwards.

From Python:

from kdenlivelib import Profile, Project
from verify import verify_project

p = Project(Profile.hd1080p60())
for clip in clips:
    p.append(clip, seconds=1.5)
p.save("assembly.kdenlive")

for r in verify_project("assembly.kdenlive"):
    print(r.name, r.verdict)          # match / MISMATCH

MCP server

bin/kdenlive-mcp speaks stdio. Point a client at it:

{"mcpServers": {"kdenlive": {"command": "/path/to/kdenlive-editing-mcp/bin/kdenlive-mcp"}}}

The tools are coarse on purpose. The useful unit of work is a whole project file; an agent placing clips one call at a time would get the frame arithmetic wrong in exactly the ways CLAUDE.md describes, and nothing would report it.

Why the wrapper

• Passing width=/height= to an MLT consumer silently resets the output frame rate to 25. The render succeeds with the right number of frames, stamped at the wrong rate, so the file reports the wrong duration and plays at the wrong speed.

• Kdenlive is a Flatpak, and a Flatpak has its own private /tmp. Give melt an output path there and it writes nothing and exits 0.

• A failing render still needs to look like a failure to the shell.

CLAUDE.md has the rest — memory that scales with clip count rather than timeline length, why a near-lossless proxy is slower to edit with than the phone original, and why the obvious VFR test misses real VFR footage. Each item was measured, not assumed.

Requirements

Kdenlive 26.08.1 as a Flatpak (org.kde.kdenlive, which supplies melt) or a host MLT, plus ffmpeg/ffprobe and Python 3.10+. The MCP server needs mcp (pip install -e .). Use absolute paths: the sandbox's working directory is not yours.

Note on metadata

Phone video carries creation timestamps and frequently GPS coordinates, and to_cfr() does not strip them — an edit proxy is meant to match its source. Projects also embed absolute paths into your home directory. .gitignore keeps media and .kdenlive files out of the repo for that reason; strip metadata before publishing renders.