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 managementpip install uv

Install Dependencies

cd kdenlive-mcp-serveruv 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 serveruv run kdenlive-mcp
# Or directly via Pythonuv 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 projectresult = project_new(output_path="my_project.kdenlive-cli.json", profile="hd1080p30")
# Import mediaresult = bin_import_clip(clip_path="video.mp4", name="Interview", duration=120.0)
# Add to timelineresult = timeline_add_clip(clip_id="clip0", track=0, position=0.0)
# Export XMLresult = 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 0timeline_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=<id> 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)                 # centerclip_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 projectresult = project_new(    output_path="intro_video.kdenlive-cli.json",    profile="hd1080p30",    name="Introduction")
# 2. Import mediaresult = bin_import_clip(    clip_path="interview.mp4",    name="Interview",    duration=120.0)
# 3. Add track and place clipresult = 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. Exportresult = 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)
# Setupresult = 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 filterresult = filter_add(    track_id=0,    clip_index=0,    filter_type="brightness",    params=["level=0.8"])
# Update brightnessresult = filter_set_param(    track_id=0,    clip_index=0,    filter_index=0,    parameter="level",    value="1.2")
# List filtersresult = 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)
# Setupresult = 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 markersresult = 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 guidesresult = guide_list()
# Saveresult = 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:
   • kdenlive:docproperties.version="1.1"
   • Chain-based clip structure with kdenlive:id linking to main_bin
   • Proper bin reference handling

Project Not Saving

The server auto-saves to disk after every mutation. If changes aren't persisting:

1. Verify the project path is set via project_new() or project_open()
2. Check that session_status() shows has_project: true
3. Ensure the output directory is writable

FastMCP Server Not Starting

1. Verify MCP version: uv run python3 -c "import mcp; print(mcp.__version__)"
2. Check FastMCP: uv run python3 -c "from mcp.server.fastmcp import FastMCP; print('FastMCP OK')"
3. Review logs for detailed error messages

Development

Testing

Run the test suite:

# Run all integration testsuv run python3 test_integration.py
# Test with zero-duration edge caseuv run python3 test_edge_cases.py

Code Style

The project follows PEP 8 style guidelines. Use uv run ruff check . to lint.

Adding New Tools

To add a new MCP tool:

1. Add the tool function to server.py decorated with @server.tool()
2. Import the corresponding CLI API module if needed
3. Include comprehensive docstrings with Args and Returns sections
4. Implement error handling with try/except
5. Call _save() after mutations to persist changes

Example:

@server.tool()def my_new_tool(param1: str, param2: int) -> dict[str, Any]:    """Brief description of what the tool does.
    Args:        param1: Description of param1.        param2: Description of param2.
    Returns:        Success response format.    """    err = _require_project()    if err:        return err
    try:        # Do something with the project        result = some_api_function(param1, param2)        _save()        return _ok(result)    except Exception as e:        return _err(str(e))

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: uv run pytest
5. Submit a pull request

References

• CLI-Anything Kdenlive
• Kdenlive Documentation
• FastMCP Documentation
• MLT XML Format
• Model Context Protocol