MCP Server: Kdenlive

A Python MCP server that lets Claude edit videos in Kdenlive through natural-language instructions.

124 tools, 7 resources, 130 automated tests — all tested against a real Kdenlive install and real melt renders, not mocked.

How it connects to Kdenlive

This does not remote-control a running Kdenlive window. There's no live connection to the app. (This was tested directly against Kdenlive's DBus interface, including the one method with no unmet preconditions — confirmed via Kdenlive's own source — and it still doesn't do anything when called externally on a stock install. Real live scripting exists as prior art but needs a custom-patched Kdenlive fork, which is its own separate project.)

Instead, the server directly reads and writes .kdenlive project files (Kdenlive's native XML project format) and renders through melt, Kdenlive's own real rendering engine — the same one Kdenlive itself uses. Claude calls MCP tools (add_clip, create_camera_push, start_render, ...), which edit an internal project model in memory; save_project/save_project_as writes that out as a real .kdenlive file. You then open that file in Kdenlive normally to view or tweak it by hand, or just render straight from the tools.

It also uses:

• ffmpeg / ffprobe — reads video/audio file info, makes thumbnails, extracts audio for beat detection.
• melt — actually renders finished video files, and can double-check a generated project loads correctly before you save.

Kdenlive itself doesn't need to be running at all while the server works. You only open Kdenlive when you want to look at a project or edit it by hand.

Features

Project management

Create/open/save/save-as/close/duplicate projects. Backup and restore. Multiple sequences per project (create/delete/list). Set resolution (720p/1080p/1440p/4K, landscape/vertical/square), frame rate, audio settings, and arbitrary metadata — never changed implicitly.

Media

Import video/image/audio files or whole folders. Every asset gets ffprobe'd (duration, resolution, fps, codecs, audio channels) and thumbnailed automatically, then tracked in a media index so Claude can refer to clips by id instead of re-scanning the filesystem. Duplicate detection.

Timeline editing

Add, remove, move, trim, split, duplicate, replace, slip, and slide clips. Ripple insert/delete. Reorder, group/ungroup, align, snap to markers or beats. Create/delete/mute/solo/lock tracks. Markers.

Motion & keyframes

High-level camera moves — push, pull, pan, tilt, orbit, handheld, shake, zoom-punch, impact hits — built on real easing curves (linear, ease-in/out, cubic, bezier, bounce, elastic, overshoot), not linear-only mechanical motion. Also exposes the low-level primitives directly: animate_position/scale/rotation/opacity/crop, and generic keyframing on any parameter of any effect, not just motion.

Effects

Full introspection of every effect actually installed in your Kdenlive (parsed live from its own effect definitions — nothing invented), plus 10 named presets (cinematic, punchy, vintage, dreamy, dark, high-contrast, music-video, energetic, minimal, clean). Apply, remove, enable/disable, and — critically — get/set parameters on an already-applied effect, not just at creation time.

Transitions

Crossfade, zoom, whip, slide, push, blur, flash, glitch, distortion, directional wipes, dip-to-black/white, hard cut. Each backed by a real MLT/frei0r service where one exists; where Kdenlive has no dedicated service (whip, blur, glitch), built as a documented, honest approximation rather than a fake one.

Audio & beat-sync

Waveform analysis (RMS envelope, peak, clipping), BPM/beat/downbeat detection, energy-section and structural segmentation, silence detection — all real signal analysis via librosa/ffmpeg. Beat-synced editing: cut clips on the beat, zoom/shake/flash on the beat, beat-synced montages, all with musically-varied intensity (not every beat identical). Sound-effect placement. Clip volume/gain and loudness normalization using Kdenlive's real audio effects.

Subtitles

Add/remove/edit/move/split/merge subtitle entries, import/export .srt. Stored exactly the way Kdenlive itself stores them (a sibling .srt file referenced by a filter), so a project this server edits opens identically in Kdenlive's own subtitle editor.

Rendering

Real rendering through melt — the actual engine, not a reimplementation. Runs as a background job (start_render returns immediately), with live progress polling, cancellation, and codec selection (h264/h265/vp9/prores, aac/mp3/opus). A job is never reported "completed" without ffprobe verifying the output is real, playable media.

Safety, undo, and batch operations

Every mutating tool automatically checkpoints before it runs; undo_operation/redo_operation walk that history. Named snapshots for longer-lived checkpoints. execute_batch runs a list of tool calls atomically — any failure rolls back every operation that already succeeded, leaving the project exactly as it started. All filesystem paths are validated; the server never overwrites source media or renders over an imported asset.

Generic property interface & capability detection

get_property/set_property/list_properties work uniformly across projects, sequences, tracks, clips, and effects — a forward-compatible escape hatch alongside the typed tools. get_kdenlive_capabilities reports exactly what's installed (versions, available effects/transitions) rather than assuming.

MCP Resources

Read-only, context-efficient project state exposed as resources rather than tool calls: kdenlive://project, timeline, tracks, media, effects, transitions, capabilities.

Not implemented

Media bin folders/organization, proxy media, nested sequences, reference-video style analysis, automatic stock-footage/music sourcing (would need provider API keys), a fully autonomous one-shot "make me a video" tool, and anything requiring live GUI state (current tool, selected items, playhead position) — Kdenlive has no working external control surface for that on a stock install.

Installation

Requirements: Python 3.10+, ffmpeg/ffprobe, and Kdenlive (recommended, not strictly required — see below).

1. Get the code

git clone https://github.com/12bijaya/MCP_Server_Kdenlive.git
cd MCP_Server_Kdenlive

2. Create a virtual environment and install

python3 -m venv .venv
source .venv/bin/activate          # on Windows: .venv\Scripts\activate
pip install -e ".[dev]"

3. Check it's working

pytest

You should see all tests pass. If ffmpeg/ffprobe aren't installed, install them first (sudo apt install ffmpeg on Ubuntu, brew install ffmpeg on macOS).

4. Find the path to the installed server

which kdenlive-mcp

Copy that full path — you'll need it in the next step.

5. Connect it to Claude

Claude Desktop: open its config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code: run claude mcp add -s user kdenlive /full/path/to/kdenlive-mcp, or open (or create) .mcp.json in your project folder.

Either way, for a manual config file add this (using the path from step 4):

{
  "mcpServers": {
    "kdenlive": {
      "command": "/full/path/to/MCP_Server_Kdenlive/.venv/bin/kdenlive-mcp"
    }
  }
}

Restart Claude Desktop (or start a new Claude Code session) after saving. Kdenlive tools should now show up as available.

6. (Optional) Point it at Kdenlive/melt manually

The server auto-detects a snap-installed Kdenlive on Linux. If yours is installed a different way and isn't found automatically, set these environment variables before launching Claude, or add them to the mcpServers entry above under an "env" key:

Variable	What it's for
KDENLIVE_MCP_KDENLIVE	Path to the kdenlive binary
KDENLIVE_MCP_MELT	Path to the melt binary
KDENLIVE_MCP_EFFECTS_DIR	Path to Kdenlive's effects folder

Without Kdenlive/melt installed at all, the server still works for building/saving .kdenlive files — you just lose the effects/transitions catalog, real-engine validation, and rendering.

Try it

Ask Claude something like:

Create a new 1080p project, import /home/me/footage/clip1.mp4, put it on the timeline, add a slow zoom-in over the first 2 seconds, then render it to ~/Videos/output.mp4.

Or open the saved .kdenlive project in Kdenlive directly to see/tweak the result.

Project layout

src/kdenlive_mcp/
  core/           # internal model: timeline, keyframes, effects, transitions, audio, subtitles, assets
  kdenlive/       # reads/writes .kdenlive files; effect & transition catalogs; capability detection
  media/          # ffmpeg/ffprobe wrappers, thumbnail generation, real rendering via melt
  storage/        # workspace path safety, caching, snapshots
  validation/     # project validation (structural + real-melt load check)
  mcp_tools/      # all 124 MCP tools (by category) + 7 resources + session/undo state
  server.py       # entrypoint
tests/