Kdenlive MCP Server

Kdenlive MCP Server

A Model Context Protocol (MCP) server wrapping cli-anything-kdenlive for LLM-driven video editing workflows via Kdenlive.

Overview

This FastMCP server enables AI models to perform complex video editing tasks on Kdenlive projects through a set of 75 tools. The server uses the Python API of cli-anything-kdenlive directly (not subprocess) to maintain a persistent session state, ensuring modifications are immediately available to subsequent tool calls.

Key Features

• Persistent Session State: Uses CLI's in-memory session API, auto-saves after every mutation
• Gen 5 XML Export: Kdenlive-compatible XML output with proper bin references and version metadata
• Robust Error Handling: All exceptions caught and returned as structured JSON payloads
• Auto-Project Tracking: Globally tracks project path; all tools automatically target the active project
• 75 MCP Tools: Comprehensive coverage of Kdenlive operations

Installation

Prerequisites

# Python 3.10+

Ensure uv is installed for dependency management

pip install uv

Install Dependencies

cd kdenlive-mcp-server

uv sync

Usage

As an MCP Server

The server runs as a FastMCP server compatible with any LLM platform that supports MCP (e.g., Claude Code, Pi, OpenCode).

Command Line

# Run the MCP server

uv run kdenlive-mcp

Or directly via Python

uv run python3 -m kdenlive_mcp_server.server

Python Integration

from kdenlive_mcp_server.server import (

project_new, bin_import_clip, timeline_add_clip, export_xml )

Create project

result = project_new(output_path="my_project.kdenlive-cli.json", profile="hd1080p30")

Import media

result = bin_import_clip(clip_path="video.mp4", name="Interview", duration=120.0)

Add to timeline

result = timeline_add_clip(clip_id="clip0", track=0, position=0.0)

Export XML

result = export_xml(output_path="output.kdenlive")

Project Structure

kdenlive-mcp-server/

├── kdenlive_mcp_server/ │ ├── init.py # Empty package init │ └── server.py # FastMCP server with 75 tools ├── main.py # Entry point delegating to server module ├── pyproject.toml # Project configuration and dependencies ├── uv.lock # Dependency lock file └── README.md # This file

Tools

Project (5 tools)

Bin (4 tools)

Timeline (8 tools)

Filters (5 tools)

Transitions (4 tools)

Guides (3 tools)

Export (3 tools)

Session (4 tools)

Batch Editing & Vertical Video (new in 0.2.0)

timeline_build_from_segments(clip_id, segments, track=0, start=0.0, gap=0.0, include_audio=True, audio_track=None)

Cutting a long take with timeline_split_clip / timeline_remove_clip is fragile because every removal shifts the clip_index of the clips after it. Instead, compute the ranges you want to keep and place them all at once:

timeline_add_track()  # video track 0

timeline_build_from_segments( clip_id="clip0", segments=[{"start": 0.5, "end": 1.5}, {"start": 3.0, "end": 4.5}, {"start": 6.0, "end": 8.0}], )

-> {"placed": 3, "timeline_duration": 4.5, "kept_seconds": 4.5, "track": 0, "audio_track": 1, ...}

• segments is a list of {start, end} in source seconds, or a path to a JSON file containing {"segments": [...]}.
• Segments are sorted, clamped to the clip's duration, merged where they overlap or touch, and dropped if shorter than 0.05 s. An empty result is an error.
• Segments are laid out from start, separated by gap seconds.
• Clips on a video track render without sound, so when the source has an audio stream the same segments are mirrored onto an audio track (the first existing one, or a new A1). Pass include_audio=False to skip this, or audio_track= to choose the track.
• The whole build, including any auto-created audio track, is one undo step: a single session_undo() reverts it.

clip_reframe_vertical(track_id, clip_index, x_offset=0.0)

For Shorts/Reels/TikTok, start the project with a vertical profile (vertical1080p30 or vertical1080p60, both 1080x1920), then reframe each landscape clip:

project_new("short.kdenlive-cli.json", profile="vertical1080p30")

... import + timeline_build_from_segments ...

clip_reframe_vertical(track_id=0, clip_index=0) # center clip_reframe_vertical(track_id=0, clip_index=1, x_offset=-0.5) # pan left

The source is scaled so its height fills the frame, then shifted horizontally: x_offset -1 shows the left edge, 0 the center, 1 the right edge. It adds an affine filter (Kdenlive's Transform effect) with a transition.rect; calling it again on the same clip updates that filter instead of stacking another. Center crop only, no face tracking.

Example Workflows

Create a Simple Video Project

from kdenlive_mcp_server.server import (

project_new, bin_import_clip, timeline_add_track, timeline_add_clip, export_xml, project_save )

1. Create project

result = project_new( output_path="intro_video.kdenlive-cli.json", profile="hd1080p30", name="Introduction" )

2. Import media

result = bin_import_clip( clip_path="interview.mp4", name="Interview", duration=120.0 )

3. Add track and place clip

result = timeline_add_track(track_type="video", track_name="V1") result = timeline_add_clip( clip_id="clip0", # From bin_import_clip response track=0, position=0.0 )

4. Export

result = export_xml(output_path="intro.kdenlive")

Apply Effects to Clips

from kdenlive_mcp_server.server import (

project_new, bin_import_clip, timeline_add_track, timeline_add_clip, filter_add, filter_set_param, filter_list )

Setup

result = project_new(output_path="effects_demo.kdenlive-cli.json", profile="hd720p60") result = bin_import_clip(clip_path="movie.mp4", name="Movie", duration=300.0) result = timeline_add_track(track_type="video") result = timeline_add_clip(clip_id="clip0", track=0, position=0.0)

Add brightness filter

result = filter_add( track_id=0, clip_index=0, filter_type="brightness", params=["level=0.8"] )

Update brightness

result = filter_set_param( track_id=0, clip_index=0, filter_index=0, parameter="level", value="1.2" )

List filters

result = filter_list(track_id=0, clip_index=0)

Add Chapter Markers

from kdenlive_mcp_server.server import (

project_new, bin_import_clip, timeline_add_track, timeline_add_clip, guide_add, guide_list, project_save )

Setup

result = project_new(output_path="documentary.kdenlive-cli.json", profile="4k30") result = bin_import_clip(clip_path="documentary.mp4", name="Doc", duration=900.0) result = timeline_add_track(track_type="video") result = timeline_add_clip(clip_id="clip0", track=0, position=0.0)

Add chapter markers

result = guide_add(position=60.0, label="Chapter 1: Introduction", guide_type="chapter") result = guide_add(position=180.0, label="Chapter 2: Main Content", guide_type="chapter") result = guide_add(position=300.0, label="Chapter 3: Conclusion", guide_type="chapter")

List guides

result = guide_list()

Save

result = project_save()

Error Handling

All tools return consistent response formats:

# Success

{ "success": True, "data": {...} }

Error

{ "success": False, "error": "Error message describing the failure" }

Configuration

pyproject.toml

[project]

name = "kdenlive-mcp-server" version = "0.1.0" description = "MCP server for Kdenlive video editing via cli-anything-kdenlive" requires-python = ">=3.10" dependencies = [ "mcp>=1.28.0", "cli-anything-kdenlive>=1.0.0", ]

[project.scripts] kdenlive-mcp = "kdenlive_mcp_server.server:main"

[tool.uv.sources] cli-anything-kdenlive = { git = "https://github.com/HKUDS/CLI-Anything.git", subdirectory = "kdenlive/agent-harness" }

uv.lock

Auto-generated by uv sync. Contains locked dependency versions.

Dependencies

• mcp>=1.28.0: FastMCP server framework for MCP protocol
• cli-anything-kdenlive @ git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=kdenlive/agent-harness:
• CLI harness for Kdenlive video editing via melt
• Includes Gen 5 MLT XML format rewrite (PR #216)
• Provides Python API for project management

Troubleshooting

Kdenlive XML Compatibility Issues

If Kdenlive reports "Version of the project file cannot be read" or "Timeline clip without bin reference found":

1. Cause: Using PyPI v1.0.0 (Gen 4 format) which lacks proper Kdenlive metadata
2. Fix: The package now installs from GitHub HEAD with Gen 5 format that includes: