kdenlive-mcp

Local-first, client-agnostic MCP server for Kdenlive on Linux.

Inspect, edit and render Kdenlive projects from an AI assistant, locally on Linux: timelines, media diagnostics, safe project copies, clip edits and rendering with Kdenlive presets.

pipx install mcp-kdenlive      # NOT "kdenlive-mcp": that PyPI name is an unrelated project
kdenlive-mcp diagnose

Start here: docs/user-guide.md (install, client setup, safety, upgrade, troubleshooting). The available tools are listed in docs/tools.md, and the planned work in the roadmap.

Requirements

• Linux
• Python 3.11 or newer
• Kdenlive, MLT (melt) and FFmpeg (ffprobe), installed separately from your distribution. The Python package does not install them.

Install

pipx install mcp-kdenlive

The PyPI distribution is mcp-kdenlive. The PyPI name kdenlive-mcp belongs to an unrelated project, so pipx install kdenlive-mcp installs something else. See docs/packaging.md for virtual environments, upgrades and artifact checks.

From source

git clone https://github.com/mhbxyz/kdenlive-mcp.git
cd kdenlive-mcp
uv sync            # or: python -m venv .venv && .venv/bin/pip install -e .
uv run kdenlive-mcp --version

Check your environment

uv run kdenlive-mcp diagnose          # human-readable, exit status 1 if something required is missing
uv run kdenlive-mcp diagnose --json   # machine-readable

The same report is available to MCP clients through the diagnose_environment tool.

Programs are looked up on PATH. Override their location with these environment variables:

Flatpak and Snap builds of Kdenlive do not expose kdenlive, melt or ffprobe on PATH. Point the variables above to executables or wrapper scripts.

Start the server

uv run --directory /path/to/kdenlive-mcp kdenlive-mcp     # same as: kdenlive-mcp serve

Tested clients (Claude Code, Codex CLI, OpenCode, Grok Build CLI) and copyable configurations are listed in docs/clients.md. A typical configuration:

{
  "mcpServers": {
    "kdenlive": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/kdenlive-mcp", "kdenlive-mcp"],
      "env": { "KDENLIVE_MCP_KDENLIVE": "/usr/bin/kdenlive" }
    }
  }
}

MCP clients often start servers with a reduced environment. If tools are reported missing from a client but not from your shell, pass PATH or the KDENLIVE_MCP_* variables explicitly.

To try the server with the official MCP Inspector:

npx @modelcontextprotocol/inspector --cli uv run --directory "$PWD" kdenlive-mcp --method tools/list

Development

uv sync
uv run pytest            # unit + protocol tests; integration tests skip when tools are missing

Architecture: domain modules (environment.py, process.py) do not depend on MCP. server.py is the only MCP transport layer.

Documentation:

• User guide
• Releasing (maintainers)
• Contributing
• Tools
• Clients
• Compatibility
• Versioning
• Security model
• Security policy (reporting vulnerabilities)
• Incident response
• Packaging
• MCP Registry
• Changelog
• Research