kdenlive-mcp
Provides tools for building and editing video timelines with Kdenlive/MLT, including project creation, media scanning, clip and effect management, preview frame generation, validation, rendering to H.264/AAC, and exporting/importing .kdenlive projects.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
kdenlive-mcp
English | Español
An MCP server for editing video on Linux with Kdenlive/MLT: the edit lives in a JSON
EDL, preview frames come back as images, and rendering goes through melt.
Why
Video-editing integrations usually either drive a GUI or ask the model to edit MLT XML directly. Both are fragile: a GUI needs a display and its state can change underneath you, while XML has many coupled properties and no useful error messages.
This server keeps the editable document and the build output separate:
The EDL JSON is the source of truth.
project.edl.jsonis small, diffable and written atomically. Every editing tool modifies this file, never the XML.The
.kdenlivefile is a build artifact.export_kdenlive(andrender/preview/validateinternally) compile the EDL into a real Kdenlive project. You can throw it away and regenerate it after any edit.meltrenders instead of the GUI. It is the same MLT engine Kdenlive uses, but headless, deterministic and scriptable. No X session is needed to edit, preview or render.previewreturns frames as images. A low-resolution render plus JPEG frames in the MCP response lets the agent actually look at the result and fix it, instead of guessing from metadata.
A human can still open the compiled .kdenlive in the Kdenlive GUI, polish it by hand,
and bring it back into the EDL with import_kdenlive (best effort, see
Limitations).
media_scan --> project_create --> clip_add / clip_update / effect_add --> preview --> frames
| | |
| | +--> look, fix, repeat
| +--> low-res .mp4
v
project.edl.json (source of truth)
|
+--------------------------+--------------------------+
| | |
v v v
export_kdenlive validate render
| | |
v v v
project.kdenlive XML + null render final .mp4
|
v
Kdenlive GUI (optional)Related MCP server: kdenlive-mcp
Features
20 MCP tools covering projects, media, tracks, clips, effects, preview, render, validation, export/import and output checks.
Media, solid-color and title clips, with fades, linear audio gain and raw MLT filters.
previewrenders a small H.264 file and returns up to 24 frames inline as JPEG images.renderproduces H.264/AAC with configurable CRF, preset, output size and time range. A missing output dimension is derived from the project aspect ratio.validatechecks XML well-formedness, reports missing media and runs a fullmeltrender to the null consumer..kdenliveexport and import;open_in_kdenlivecan launch the GUI when one is installed.output_checkreports streams, duration and audio peak level, catching silent renders.Zero third-party Python dependencies: standard library only (Python 3.9+).
Clear validation errors for overlapping clips, duplicate tracks, unknown ids, bad profiles and malformed times.
No GUI or X session required for editing, previewing, validating or rendering.
Requirements
Python 3.9+. The server uses only the standard library.
ffmpegandffprobeonPATH: media probing, frame extraction and loudness measurement.melt(from MLT) onPATH: compiling is done in Python, but rendering and validation runmelt. This project is developed against MLT 7.42.kdenlive(optional): only needed foropen_in_kdenliveand for opening exported projects in the GUI. Tested with Kdenlive 26.08.3.Linux. The process handling, path assumptions and GUI launching target POSIX systems; macOS and Windows are not tested.
Installation
From a clone (zero install)
The server has no Python dependencies, so cloning is enough:
git clone https://github.com/kikoperex/kdenlive-mcp.git
cd kdenlive-mcp
python3 server.py --version # kdenlive-mcp 1.0.0
python3 server.py --list-tools # one tool name per line, 20 in totalFor the examples below the checkout is assumed to be at
$HOME/mcp/kdenlive-mcp; adjust the path if yours differs. server.py is a thin
launcher for the kdenlive_mcp package; the equivalent package entry point is
python3 -m kdenlive_mcp, which runs from the checkout root.
With pipx or uvx
The project ships a pyproject.toml with a kdenlive-mcp console script:
# from a checkout
pipx install .
# or directly from Git, without a manual clone
uvx --from git+https://github.com/kikoperex/kdenlive-mcp kdenlive-mcpAfter installing, run kdenlive-mcp --version or point the MCP client at the
installed command. Both forms also accept --list-tools.
Register with pi
pi mcp add kdenlive \
--description "Kdenlive/MLT video editing: build timelines, render, preview frames" \
--exposure codemode \
-- python3 $HOME/mcp/kdenlive-mcp/server.pyRenders are slow, and the default per-request timeout of 60 seconds is too short for
real footage. Raise it in ~/.pi/agent/mcp.json:
python3 - <<'EOF'
import json, pathlib
p = pathlib.Path.home() / ".pi/agent/mcp.json"
c = json.loads(p.read_text())
c["mcpServers"]["kdenlive"]["timeout"] = 3600
p.write_text(json.dumps(c, indent=2) + "\n")
EOF
pi mcp list # kdenlive should be connected and list 20 toolsPi can expose the tools in three modes:
Exposure | How the model reaches the tools | When to use it |
| From codemode scripts; tools are discoverable with | Chaining many edits in one script |
| Found through | Keep the tool list small but call tools directly |
| Declared to the model like built-in tools on every turn | Frequent, simple use; costs 20 tool declarations |
Set it with --exposure deferred (or direct) when adding the server, or "exposure"
in the server entry in mcp.json.
Generic MCP client
Any stdio MCP client can launch the server directly:
{
"mcpServers": {
"kdenlive": {
"command": "python3",
"args": ["/home/USER/mcp/kdenlive-mcp/server.py"]
}
}
}Replace /home/USER with the absolute path on your machine (JSON does not expand
$HOME). Timeout keys and exposure modes are client-specific; on pi they are timeout
and exposure in seconds and mode names as above.
Rendering has two timeouts: the MCP client's per-request timeout (set it high enough for
the whole call) and the tool's own subprocess timeout. render defaults to 7200 seconds
and accepts timeout; preview defaults to 1800 seconds. For long renders, raise both.
Tools
Tool | Purpose | Main arguments |
| Create a new EDL and return its timeline. Defaults to 1920x1080 at 25 fps. |
|
| Print tracks, clips, in/out points, fades, gain, effects and total duration. |
|
| Change frame size, frame rate or progressive flag. |
|
| Inspect one or more media files: duration, resolution, fps, codecs, audio streams, interlacing. |
|
| List usable media in a directory with metadata. |
|
| Add a video or audio track; the name defaults to the next free |
|
| Remove a track and everything on it. |
|
| Place a media, color or title clip. Media uses |
|
| Move, retime, trim, re-gain, fade or relabel a clip; can also move it to another track. Accepts the same timing fields as |
|
| Delete a clip from the timeline. |
|
| Split a clip at an absolute timeline position; both halves must be at least one frame. |
|
| Append a raw MLT filter to a clip, for example |
|
| Remove all effects from a clip, or only one service. |
|
| Fast low-resolution render plus up to 24 frames returned as images. |
|
| Render the timeline to H.264/AAC. CRF defaults to 20, preset to |
|
| Compile the project, check XML parsing and missing media, then run a full |
|
| Compile the EDL into a |
|
| Compile the project and launch it in the Kdenlive GUI. Requires |
|
| Convert an existing |
|
| Inspect a rendered file: streams, duration and audio peak; warns when the output looks silent. |
|
Relative to the EDL path, derived files are siblings:
editbecomesedit.edl.json;edit.jsonis also accepted as an EDL path.edit.edl.jsoncompiles toedit.kdenlive.renderwritesedit.mp4unlessoutis given.previewwritesedit.preview.mp4unlessoutis given.
Time formats and semantics
Times may be numbers in seconds or strings in any of these forms:
3.5 # number, seconds
"3.5s" # seconds
"87f" # 87 frames at the project frame rate
"00:00:03.500" # HH:MM:SS.mmmThe EDL stores seconds as floats. Frame values are converted using the project's fps,
and generated MLT timecodes are snapped to whole frames.
startis the position on the timeline;inandoutare positions in the source media. For a media clip,durationis the length on the timeline; whenoutis used,duration = out - in. If onlyinis given, the clip runs to the end of the source.fade_inandfade_outare seconds. Video fades go through black; audio fades change the volume.gainis a linear multiplier:1.0is unity,0.5is approximately -6 dB,2.0is approximately +6 dB, and0is silent. The generated Kdenlive volume filter stores the converted value in dB.Clips on the same track are linear and may not overlap. Conflicting edits fail with the occupied time range; use
clip_updateto move/trim, orappend/append: trueto place a clip after the last one.Video tracks composite from bottom to top: V2 covers V1. Audio tracks mix independently.
Audio on a video track is muted by default (the generated track has
hide="audio"), so music and voice belong on audio tracks. Put audio-only files on anAtrack.
Notes on the .kdenlive format
The generator is written against the Kdenlive 26.08 project format and MLT 7.42. These properties are load-bearing:
The document UUID lives in
main_binaskdenlive:docproperties.uuidand must equal the sequence tractor'skdenlive:sequenceproperties.documentuuid; otherwise Kdenlive treats the sequence as foreign.Video tracks are numbered V1..Vn in tractor order, but audio numbering is reversed: the last audio track in the tractor is A1. Tracks are therefore emitted V1..Vn, then An..A1.
Video compositing uses
qtblendand audio mixing usesmix, bothalways_activeand marked withinternal_addedso Kdenlive does not show them as user-added transitions.black_trackis pinned to the content duration. MLT derives a tractor's length from its longest track, so this keeps the sequence from running longer than the edit.Title clips need an empty
resourceand inlinexmldata; that makes thekdenlivetitlemodule read the inline title instead of trying to load a file.brightness.levelis a 0..1 multiplier, whilevolume.levelis in dB (0 dB is unity). Fades are written using those scales.The root
<mlt producer="...">points at the sequence tractor so thatmelt project.kdenliverenders the timeline. Kdenlive itself does not read that attribute; it looks upmain_bin.
Testing
python3 tests/test_e2e.pyThe end-to-end test requires ffmpeg, ffprobe and melt. It generates 640x360 sample
media in /tmp/kdenlive-mcp-test (override with KD_TEST_DIR), starts server.py, and
speaks newline-delimited JSON-RPC over stdio like a real client.
The suite has 48+ checks and takes about two minutes. It verifies tool schemas, media
probing/scanning, editing and overlap rejection, profile/track changes, .kdenlive
export and import (including fades and audio gain), preview image counts and aspect
ratio, render duration and sizing, and actual pixels (color clip, red clip, fade to
black, visible title), plus audio peak, large requests and error handling. CI runs the
same command on Python 3.9 and 3.12.
Troubleshooting
meltexits with signal 11 (segfault). This is usually the output size, not the timeline. Use even dimensions, preferably multiples of 16:320x180,640x360,1280x720.renderandpreviewsnap requested sizes to even pixel counts, but very small or unusual sizes can still upset libx264; try another size.kdenlive --rendersegfaults. On Kdenlive 26.08.3 (Arch), headless rendering crashes even on an empty project. This server never uses it: rendering and validation go throughmelt.The MCP call times out during a render. Raise the client's per-request timeout (
"timeout": 3600or more inmcp.json) and, for very long jobs, pass a largertimeouttorender. The tool's default is 7200 seconds;previewdefaults to 1800.required executable not found: melt,ffmpegorffprobe. Install MLT and FFmpeg and make sure their binaries are onPATH(the server also checks/usr/binand/sbinformelt).The render has no audio. Check it with
output_check; a peak below -60 dB is reported as silent. Audio placed on a video track is muted by design, so move it to an audio track.Preview frames are missing.
previewcaps output at 24 frames and omits individual JPEGs larger than about 900 KB. Retry with a smallerwidth.open_in_kdenlivefails. It needskdenliveinstalled and a graphical session; editing, previewing and rendering do not.
Limitations
import_kdenliveis best effort. It recovers track layout, clip positions and sources, color clips, title text, simple brightness fades, and constant audio gain plus simple volume fades. It does not recover transitions, per-clip effect stacks, arbitrary keyframe curves, groups or markers. Clips whose media file no longer exists are skipped.There is no file locking. Two agents or processes editing the same EDL can overwrite each other's changes (the last atomic save wins). Use one EDL per editor or serialize edits.
The EDL model is intentionally small: one sequence, cuts and simple fades, plus raw per-clip filters. There are no transitions, keyframed effects, markers, groups, proxy workflows or multiple sequences.
Linux-only assumptions: POSIX process groups,
shutil.which, GUI launching and filesystem paths. No Windows or macOS support is claimed.Rendering is fixed to H.264/AAC with libx264; there is no GPU encoding.
The generated
.kdenlivetargets the Kdenlive 26.08 format. Other versions may load it with warnings or reject newer properties.
Contributing
See CONTRIBUTING.md for how to report issues and submit changes. Run
python3 tests/test_e2e.py before opening a pull request.
License
kdenlive-mcp is free software licensed under the GNU General Public License, version 2
or (at your option) any later version (GPL-2.0-or-later). See LICENSE for
the full text. It is distributed without any warranty, to the extent permitted by law.
ffmpeg, ffprobe, melt/MLT and Kdenlive are separate programs invoked as
subprocesses. They are not bundled with this repository and are distributed under their
own licenses and terms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
Open-source AI video editor: cut, caption, clip and animate real Revline projects from your agent.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Render an MP4 from your own images, clips, voice-over and timed captions. JSON to video.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides a headless video editing workflow using portable JSON projects and Kdenlive for review, enabling automated video rendering and project management.19Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables automated, transactional video editing for Kdenlive, providing tools for timeline manipulation, effects, graphics, captions, visualization, and project export through a local MCP server and scriptable CLI.MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to drive a local explanatory-video lab over stdio: inspecting and patching declarative scenes and a multilayer timeline (clips, titles, captions, voice, music), querying media and frames, rendering previews, running recoverable jobs, and exporting bundles. It also handles Kdenlive round-trip sync plus checkpoints, undo and restore, all offline with JSON responses.MIT
- AlicenseNot gradedqualityBmaintenanceEnables local-first video editing through the Model Context Protocol by maintaining versioned JSON projects, applying revision-checked timeline edits, compiling deterministic MLT, queuing renders, generating previews, and verifying outputs with local Kdenlive/MLT and FFmpeg tools.2Apache 2.0