Kdenlive MCP Server

Kdenlive MCP 服务

一个封装 cli-anything-kdenlive 的模型上下文协议（MCP）服务，可通过 Kdenlive 支持由大模型驱动的视频编辑工作流。

概述

此 FastMCP 服务提供 75 个工具，使 AI 模型能够对 Kdenlive 项目执行复杂的视频编辑任务。服务直接使用 cli-anything-kdenlive 的 Python API（而非子进程）来维持持久会话状态，确保修改可立即供后续工具调用使用。

主要功能

• 持久会话状态：使用 CLI 的内存会话 API，并在每次修改后自动保存
• 第 5 代 XML 导出：输出兼容 Kdenlive 的 XML，包含正确的素材箱引用和版本元数据
• 可靠的错误处理：捕获所有异常，并以结构化 JSON 载荷形式返回
• 自动项目跟踪：全局跟踪项目路径；所有工具都会自动针对当前活动项目
• 75 个 MCP 工具：全面覆盖 Kdenlive 操作

安装

先决条件

# Python 3.10+
# Ensure uv is installed for dependency management
pip install uv

安装依赖项

cd kdenlive-mcp-server
uv sync

使用方法

作为 MCP 服务

此服务以 FastMCP 服务运行，兼容所有支持 MCP 的大模型平台（例如 Claude Code、Pi、OpenCode）。

命令行

# Run the MCP server
uv run kdenlive-mcp

# Or directly via Python
uv run python3 -m kdenlive_mcp_server.server

Python 集成

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")

项目结构

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

工具

项目（5 个工具）

工具	描述
project_new()	创建新的 Kdenlive 项目，可选择覆盖配置文件
project_open()	加载现有的 .kdenlive-cli.json 项目
project_save()	将当前项目状态保存到磁盘
project_get_info()	获取项目元数据（分辨率、FPS、轨道布局、片段数量）
project_list_profiles()	列出所有可用的视频输出配置文件（hd1080p30、4k60、sd_pal 等）

素材箱（4 个工具）

工具	描述
bin_import_clip()	将媒体文件（视频、音频、图像）导入项目素材箱
bin_remove_clip()	按 ID 从素材箱中删除片段
bin_list_clips()	列出项目素材箱中的所有素材
bin_get_clip_details()	获取片段的详细属性（时长、类型、来源）

时间线（8 个工具）

工具	描述
timeline_add_track()	向时间线添加视频或音频轨道
timeline_remove_track()	删除轨道及其所有片段
timeline_add_clip()	将素材箱中的片段放置到轨道的指定位置
timeline_remove_clip()	从轨道中移除片段
timeline_move_clip()	在同一轨道上重新定位片段
timeline_trim_clip()	调整片段的入点/出点裁剪手柄
timeline_split_clip()	在精确偏移处将片段剪切成两段
timeline_list()	列出所有轨道及其片段数量和状态

滤镜（5 个工具）

工具	描述
filter_add()	添加视频/音频效果（模糊、亮度、frei0r.opacity、音量）
filter_remove()	从片段中移除效果
filter_set_param()	更新单个滤镜参数（半径、不透明度、级别）
filter_list()	列出片段上所有启用的滤镜
filter_list_available()	按类别查找所有可用滤镜

转场（4 个工具）

工具	描述
transition_add()	创建混合转场（溶解、擦除、滑动、合成、仿射）
transition_remove()	按 ID 删除转场
transition_set()	更新转场参数
transition_list()	列出时间线上的所有转场

指引标记（3 个工具）

工具	描述
guide_add()	添加时间线标记/章节
guide_remove()	按 ID 移除指引标记
guide_list()	列出所有指引标记

导出（3 个工具）

工具	描述
export_xml()	为项目生成 Kdenlive/MLT XML
export_list_presets()	列出可用的渲染预设
export_render()	通过 melt CLI 将项目渲染为视频

会话（4 个工具）

工具	描述
session_undo()	撤销最近一次操作（最多支持 50 条历史记录）
session_redo()	重做上次撤销的操作
session_status()	检查会话状态（是否已加载项目、修改标记、历史记录深度）
session_history()	列出所有撤销/重做历史记录

批量编辑与竖屏视频（0.2.0 中新增）

工具	描述
timeline_build_from_segments()	在一次操作中将同一个素材箱片段的多个保留片段首尾相接地放置，并且只占用一次撤销步骤
clip_reframe_vertical()	将 16:9 片段居中裁剪，以填充 9:16 画面，并支持水平平移

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

使用 timeline_split_clip / timeline_remove_clip 剪辑较长的素材容易出错，因为每次移除都会改变后续片段的 clip_index。因此，请计算要保留的范围，并一次性放置所有片段：

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 是由 {start, end} 组成的列表（单位为源素材秒数），也可以是包含 {"segments": [...]} 的 JSON 文件路径。
• 片段会排序、裁剪至素材时长范围内、合并重叠或相接的片段，并删除时长短于 0.05 s 的片段。结果为空时会报错。
• 片段从 start 开始排列，彼此间隔 gap 秒。
• 视频轨道上的片段不会渲染声音，因此如果源素材包含音频流，相同的片段也会镜像到音频轨道上（第一个现有音轨，或新建的 A1）。传入 include_audio=False 可跳过此操作，或传入 audio_track=<id> 来选择音轨。
• 整个构建过程（包括自动创建的音轨）只占用一个撤销步骤： 一次 session_undo() 即可撤销。

clip_reframe_vertical(track_id, clip_index, x_offset=0.0)

制作 Shorts/Reels/TikTok 视频时，请先使用竖屏配置文件（vertical1080p30 或 vertical1080p60，两者均为 1080x1920）创建项目，然后重新构图每个横屏片段：

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

源素材会按比例缩放，使其高度填满画面，然后水平移动： x_offset 为 -1 时显示左边缘，为 0 时显示中心，为 1 时显示右边缘。此操作会添加 affine 滤镜（Kdenlive 的 Transform 效果）和 transition.rect；在同一片段上再次调用时，会更新该滤镜，而不会叠加另一个滤镜。仅支持居中裁剪，不支持人脸跟踪。

工作流示例

创建简单的视频项目

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")

为片段应用效果

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)

添加章节标记

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()

错误处理

所有工具都会返回一致的响应格式：

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

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

配置

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

由 uv sync 自动生成。包含已锁定的依赖版本。

依赖项

• mcp>=1.28.0：用于 MCP 协议的 FastMCP 服务框架
• **cli-anything-kdenlive @ git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=kdenlive/agent-harness**：
  • 通过 melt 编辑 Kdenlive 视频的 CLI 工具集
  • 包含 Gen 5 MLT XML 格式重写（PR #216）
  • 提供用于项目管理的 Python API

故障排除

Kdenlive XML 兼容性问题

如果 Kdenlive 报告“无法读取项目文件版本”或“发现不含素材箱引用的时间线片段”：

1. 原因：使用了 PyPI v1.0.0（Gen 4 格式），该版本缺少正确的 Kdenlive 元数据
2. 修复方法：该软件包现在从 GitHub HEAD 安装，采用包含以下内容的 Gen 5 格式：
   • kdenlive:docproperties.version="1.1"
   • 基于链的片段结构，通过 kdenlive:id 链接到 main_bin
   • 正确处理素材箱引用

项目未保存

每次发生变更后，服务都会自动保存到磁盘。如果更改未能持久保存：

1. 确认已通过 project_new() 或 project_open() 设置项目路径
2. 检查 session_status() 是否显示 has_project: true
3. 确保输出目录可写

FastMCP 服务无法启动

1. 确认 MCP 版本：uv run python3 -c "import mcp; print(mcp.__version__)"
2. 检查 FastMCP：uv run python3 -c "from mcp.server.fastmcp import FastMCP; print('FastMCP OK')"
3. 查看日志以获取详细错误信息

开发

测试

运行测试套件：

# Run all integration tests
uv run python3 test_integration.py

# Test with zero-duration edge case
uv run python3 test_edge_cases.py

代码风格

本项目遵循 PEP 8 风格指南。使用 uv run ruff check . 进行代码检查。

添加新工具

添加新的 MCP 工具：

1. 将工具函数添加到 server.py，并使用 @server.tool() 装饰
2. 如有需要，导入相应的 CLI API 模块
3. 添加完整的文档字符串，包含 Args 和 Returns 部分
4. 使用 try/except 实现错误处理
5. 在发生变更后调用 _save() 以持久保存更改

示例：

@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))

贡献

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过：uv run pytest
5. 提交 pull request

参考资料

• CLI-Anything Kdenlive
• Kdenlive 文档
• FastMCP 文档
• MLT XML 格式
• Model Context Protocol