Kdenlive MCP Server

Kdenlive MCP サーバー

Kdenlive を介した LLM 主導の動画編集ワークフローのために、cli-anything-kdenlive をラップする Model Context Protocol（MCP）サーバーです。

概要

この FastMCP サーバーを使用すると、AI モデルは 75 個のツールを通じて、Kdenlive プロジェクトで複雑な動画編集タスクを実行できます。サーバーは cli-anything-kdenlive の Python API を直接使用し（サブプロセスは使用しません）、セッション状態を維持します。これにより、変更内容は後続のツール呼び出しですぐに利用できます。

主な機能

• 永続的なセッション状態：CLI のメモリ内セッション API を使用し、変更のたびに自動保存します
• Gen 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 サーバーとして

このサーバーは、MCP をサポートするあらゆる LLM プラットフォーム（例：Claude Code、Pi、OpenCode）と互換性のある FastMCP サーバーとして動作します。

コマンドライン

# 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()	指定したオフセットでクリップを 2 つに分割します
timeline_list()	すべてのトラックをクリップ数と状態とともに一覧表示します

フィルター（5 個のツール）

ツール	説明
filter_add()	動画／音声エフェクト（blur、brightness、frei0r.opacity、volume）を適用します
filter_remove()	クリップからエフェクトを削除します
filter_set_param()	1 つのフィルターパラメーター（radius、opacity、level）を更新します
filter_list()	クリップで有効なフィルターをすべて一覧表示します
filter_list_available()	カテゴリ別に利用可能なすべてのフィルターを確認します

トランジション（4 個のツール）

ツール	説明
transition_add()	ブレンドトランジション（dissolve、wipe、slide、composite、affine）を作成します
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()	1 つのビン内クリップから複数のキープセグメントを連続して配置します。1 回の取り消し操作にまとめられます
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 秒未満の範囲は除外されます。結果が空の場合はエラーになります。
• セグメントは start から配置され、間には gap 秒の間隔が設けられます。
• 動画トラック上のクリップは音声なしでレンダリングされるため、ソースに音声ストリームがある場合は、 同じセグメントが音声トラックにも複製されます（最初の既存トラック、または新しい A1）。 これを省略するには include_audio=False を指定し、トラックを選択するには audio_track=<id> を指定します。
• 自動作成された音声トラックを含め、ビルド全体が 1 回の取り消し操作にまとめられます。 session_undo() を 1 回実行すると、すべて取り消されます。

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 の変形エフェクト）と 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. 原因：適切な Kdenlive メタデータが含まれていない PyPI v1.0.0（Gen 4 形式）を使用しています
2. 解決方法：このパッケージは現在、以下を含む Gen 5 形式の GitHub HEAD からインストールされます：
   • 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 のセクションを含む、充実した docstring を記述します
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. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 新しい機能のテストを追加します
4. すべてのテストが成功することを確認します：uv run pytest
5. プルリクエストを送信します

参考資料

• CLI-Anything Kdenlive
• Kdenlive ドキュメント
• FastMCP ドキュメント
• MLT XML フォーマット
• Model Context Protocol