Skip to main content
Glama

kdenlive-mcp

English | Español

CI License: GPL-2.0-or-later Python 3.9+

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.json is small, diffable and written atomically. Every editing tool modifies this file, never the XML.

  • The .kdenlive file is a build artifact. export_kdenlive (and render / preview / validate internally) compile the EDL into a real Kdenlive project. You can throw it away and regenerate it after any edit.

  • melt renders 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.

  • preview returns 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.

  • preview renders a small H.264 file and returns up to 24 frames inline as JPEG images.

  • render produces H.264/AAC with configurable CRF, preset, output size and time range. A missing output dimension is derived from the project aspect ratio.

  • validate checks XML well-formedness, reports missing media and runs a full melt render to the null consumer.

  • .kdenlive export and import; open_in_kdenlive can launch the GUI when one is installed.

  • output_check reports 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.

  • ffmpeg and ffprobe on PATH: media probing, frame extraction and loudness measurement.

  • melt (from MLT) on PATH: compiling is done in Python, but rendering and validation run melt. This project is developed against MLT 7.42.

  • kdenlive (optional): only needed for open_in_kdenlive and 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 total

For 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-mcp

After 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.py

Renders 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 tools

Pi can expose the tools in three modes:

Exposure

How the model reaches the tools

When to use it

codemode (default)

From codemode scripts; tools are discoverable with searchTools() / describeTool()

Chaining many edits in one script

deferred

Found through tool_search before use

Keep the tool list small but call tools directly

direct

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

project_create

Create a new EDL and return its timeline. Defaults to 1920x1080 at 25 fps.

path, width, height, fps, profile (e.g. 1080p25, 720p30, vertical1080, 4k30), name

project_show

Print tracks, clips, in/out points, fades, gain, effects and total duration.

edl

project_set_profile

Change frame size, frame rate or progressive flag.

edl, width, height, fps, progressive

media_probe

Inspect one or more media files: duration, resolution, fps, codecs, audio streams, interlacing.

path or paths

media_scan

List usable media in a directory with metadata.

dir, recursive

track_add

Add a video or audio track; the name defaults to the next free Vn / An.

edl, type, name

track_remove

Remove a track and everything on it.

edl, track

clip_add

Place a media, color or title clip. Media uses in/out in source seconds; color needs duration; title takes {text, style} and a duration (5 s if omitted). append places it after the last clip.

edl, track, kind, media / color / title, start, in, out, duration, gain, fade_in, fade_out, label, append

clip_update

Move, retime, trim, re-gain, fade or relabel a clip; can also move it to another track. Accepts the same timing fields as clip_add.

edl, clip_id, track, start, duration, in, out, gain, fade_in, fade_out, label, title

clip_remove

Delete a clip from the timeline.

edl, clip_id

clip_split

Split a clip at an absolute timeline position; both halves must be at least one frame.

edl, clip_id, at

effect_add

Append a raw MLT filter to a clip, for example brightness with {level: 0.8} or frei0r.cartoon. Props are passed through unchanged.

edl, clip_id, service, props

effect_remove

Remove all effects from a clip, or only one service.

edl, clip_id, service

preview

Fast low-resolution render plus up to 24 frames returned as images.

edl, times or count (default 4), width (default 320), inline, out

render

Render the timeline to H.264/AAC. CRF defaults to 20, preset to medium.

edl, out, crf, preset, width or height (the other is derived), start, end, timeout

validate

Compile the project, check XML parsing and missing media, then run a full melt render to the null consumer.

edl, out (.kdenlive path)

export_kdenlive

Compile the EDL into a .kdenlive project for the GUI.

edl, out

open_in_kdenlive

Compile the project and launch it in the Kdenlive GUI. Requires kdenlive and a graphical session.

edl, out

import_kdenlive

Convert an existing .kdenlive project back into an EDL (best effort).

project, edl

output_check

Inspect a rendered file: streams, duration and audio peak; warns when the output looks silent.

file

Relative to the EDL path, derived files are siblings:

  • edit becomes edit.edl.json; edit.json is also accepted as an EDL path.

  • edit.edl.json compiles to edit.kdenlive.

  • render writes edit.mp4 unless out is given.

  • preview writes edit.preview.mp4 unless out is 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.mmm

The EDL stores seconds as floats. Frame values are converted using the project's fps, and generated MLT timecodes are snapped to whole frames.

  • start is the position on the timeline; in and out are positions in the source media. For a media clip, duration is the length on the timeline; when out is used, duration = out - in. If only in is given, the clip runs to the end of the source.

  • fade_in and fade_out are seconds. Video fades go through black; audio fades change the volume.

  • gain is a linear multiplier: 1.0 is unity, 0.5 is approximately -6 dB, 2.0 is approximately +6 dB, and 0 is 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_update to move/trim, or append / append: true to 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 an A track.

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_bin as kdenlive:docproperties.uuid and must equal the sequence tractor's kdenlive: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 qtblend and audio mixing uses mix, both always_active and marked with internal_added so Kdenlive does not show them as user-added transitions.

  • black_track is 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 resource and inline xmldata; that makes the kdenlivetitle module read the inline title instead of trying to load a file.

  • brightness.level is a 0..1 multiplier, while volume.level is in dB (0 dB is unity). Fades are written using those scales.

  • The root <mlt producer="..."> points at the sequence tractor so that melt project.kdenlive renders the timeline. Kdenlive itself does not read that attribute; it looks up main_bin.

Testing

python3 tests/test_e2e.py

The 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

  • melt exits with signal 11 (segfault). This is usually the output size, not the timeline. Use even dimensions, preferably multiples of 16: 320x180, 640x360, 1280x720. render and preview snap requested sizes to even pixel counts, but very small or unusual sizes can still upset libx264; try another size.

  • kdenlive --render segfaults. On Kdenlive 26.08.3 (Arch), headless rendering crashes even on an empty project. This server never uses it: rendering and validation go through melt.

  • The MCP call times out during a render. Raise the client's per-request timeout ("timeout": 3600 or more in mcp.json) and, for very long jobs, pass a larger timeout to render. The tool's default is 7200 seconds; preview defaults to 1800.

  • required executable not found: melt, ffmpeg or ffprobe. Install MLT and FFmpeg and make sure their binaries are on PATH (the server also checks /usr/bin and /sbin for melt).

  • 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. preview caps output at 24 frames and omits individual JPEGs larger than about 900 KB. Retry with a smaller width.

  • open_in_kdenlive fails. It needs kdenlive installed and a graphical session; editing, previewing and rendering do not.

Limitations

  • import_kdenlive is 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 .kdenlive targets 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a headless video editing workflow using portable JSON projects and Kdenlive for review, enabling automated video rendering and project management.
      19
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      2
      Apache 2.0