{
  "markdown": "<!-- mcp-name: io.github.va1bhav512/kdenlive-mcp-server -->\n\n# Kdenlive MCP Server\n\nA Model Context Protocol (MCP) server wrapping `cli-anything-kdenlive` for LLM-driven video editing workflows via Kdenlive.\n\n## Overview\n\nThis FastMCP server enables AI models to perform complex video editing tasks on Kdenlive projects through a unified set of 36 tools organized into 8 functional categories. 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.\n\n### Key Features\n\n- **Persistent Session State**: Uses CLI's in-memory session API, auto-saves after every mutation\n- **Gen 5 XML Export**: Kdenlive-compatible XML output with proper bin references and version metadata\n- **Robust Error Handling**: All exceptions caught and returned as structured JSON payloads\n- **Auto-Project Tracking**: Globally tracks project path; all tools automatically target the active project\n- **36 MCP Tools**: Comprehensive coverage of Kdenlive operations\n\n## Installation\n\n### Prerequisites\n\n```bash\n# Python 3.10+\n# Ensure uv is installed for dependency management\npip install uv\n```\n\n### Install Dependencies\n\n```bash\ncd kdenlive-mcp-server\nuv sync\n```\n\n## Usage\n\n### As an MCP Server\n\nThe server runs as a FastMCP server compatible with any LLM platform that supports MCP (e.g., Claude Code, Pi, OpenCode).\n\n### Command Line\n\n```bash\n# Run the MCP server\nuv run kdenlive-mcp\n\n# Or directly via Python\nuv run python3 -m kdenlive_mcp_server.server\n```\n\n### Python Integration\n\n```python\nfrom kdenlive_mcp_server.server import (\n    project_new, bin_import_clip, timeline_add_clip, export_xml\n)\n\n# Create project\nresult = project_new(output_path=\"my_project.kdenlive-cli.json\", profile=\"hd1080p30\")\n\n# Import media\nresult = bin_import_clip(clip_path=\"video.mp4\", name=\"Interview\", duration=120.0)\n\n# Add to timeline\nresult = timeline_add_clip(clip_id=\"clip0\", track=0, position=0.0)\n\n# Export XML\nresult = export_xml(output_path=\"output.kdenlive\")\n```\n\n## Project Structure\n\n```\nkdenlive-mcp-server/\n├── kdenlive_mcp_server/\n│   ├── __init__.py           # Empty package init\n│   └── server.py             # FastMCP server with 36 tools (876 lines)\n├── main.py                   # Entry point delegating to server module\n├── pyproject.toml            # Project configuration and dependencies\n├── uv.lock                   # Dependency lock file\n└── README.md                 # This file\n```\n\n## Tools\n\n### Project (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `project_new()` | Create a new Kdenlive project with optional profile override |\n| `project_open()` | Load an existing .kdenlive-cli.json project |\n| `project_save()` | Persist the current project state to disk |\n| `project_get_info()` | Get project metadata (resolution, FPS, track layout, clip counts) |\n| `project_list_profiles()` | List all available video output profiles (hd1080p30, 4k60, sd_pal, etc.) |\n\n### Bin (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `bin_import_clip()` | Ingest media files (video, audio, image) into the project bin |\n| `bin_remove_clip()` | Delete a clip from the bin by ID |\n| `bin_list_clips()` | List all assets in the project bin |\n| `bin_get_clip_details()` | Fetch detailed properties of a clip (duration, type, source) |\n\n### Timeline (8 tools)\n\n| Tool | Description |\n|------|-------------|\n| `timeline_add_track()` | Append a video or audio track to the timeline |\n| `timeline_remove_track()` | Delete a track and all its clips |\n| `timeline_add_clip()` | Place a bin clip on a track at a specific position |\n| `timeline_remove_clip()` | Remove a clip from a track |\n| `timeline_move_clip()` | Reposition a clip on the same track |\n| `timeline_trim_clip()` | Adjust clip in/out crop handles |\n| `timeline_split_clip()` | Cut a clip into two pieces at a precise offset |\n| `timeline_list()` | List all tracks with clip counts and status |\n\n### Filters (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `filter_add()` | Attach a video/audio effect (blur, brightness, frei0r.opacity, volume) |\n| `filter_remove()` | Remove an effect from a clip |\n| `filter_set_param()` | Update a single filter parameter (radius, opacity, level) |\n| `filter_list()` | List all active filters on a clip |\n| `filter_list_available()` | Discover all available filters by category |\n\n### Transitions (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `transition_add()` | Create blend transitions (dissolve, wipe, slide, composite, affine) |\n| `transition_remove()` | Delete a transition by ID |\n| `transition_set()` | Update a transition parameter |\n| `transition_list()` | List all transitions on the timeline |\n\n### Guides (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `guide_add()` | Add timeline markers/chapters |\n| `guide_remove()` | Remove a guide by ID |\n| `guide_list()` | List all guide markers |\n\n### Export (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `export_xml()` | Generate Kdenlive/MLT XML for the project |\n| `export_list_presets()` | List available render presets |\n| `export_render()` | Render project to video via melt CLI |\n\n### Session (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `session_undo()` | Revert the most recent operation (up to 50 history entries) |\n| `session_redo()` | Redo the last undone operation |\n| `session_status()` | Inspect session state (project loaded, modified flag, history depth) |\n| `session_history()` | List all undo/redo history entries |\n\n## Example Workflows\n\n### Create a Simple Video Project\n\n```python\nfrom kdenlive_mcp_server.server import (\n    project_new, bin_import_clip, timeline_add_track,\n    timeline_add_clip, export_xml, project_save\n)\n\n# 1. Create project\nresult = project_new(\n    output_path=\"intro_video.kdenlive-cli.json\",\n    profile=\"hd1080p30\",\n    name=\"Introduction\"\n)\n\n# 2. Import media\nresult = bin_import_clip(\n    clip_path=\"interview.mp4\",\n    name=\"Interview\",\n    duration=120.0\n)\n\n# 3. Add track and place clip\nresult = timeline_add_track(track_type=\"video\", track_name=\"V1\")\nresult = timeline_add_clip(\n    clip_id=\"clip0\",  # From bin_import_clip response\n    track=0,\n    position=0.0\n)\n\n# 4. Export\nresult = export_xml(output_path=\"intro.kdenlive\")\n```\n\n### Apply Effects to Clips\n\n```python\nfrom kdenlive_mcp_server.server import (\n    project_new, bin_import_clip, timeline_add_track,\n    timeline_add_clip, filter_add, filter_set_param, filter_list\n)\n\n# Setup\nresult = project_new(output_path=\"effects_demo.kdenlive-cli.json\", profile=\"hd720p60\")\nresult = bin_import_clip(clip_path=\"movie.mp4\", name=\"Movie\", duration=300.0)\nresult = timeline_add_track(track_type=\"video\")\nresult = timeline_add_clip(clip_id=\"clip0\", track=0, position=0.0)\n\n# Add brightness filter\nresult = filter_add(\n    track_id=0,\n    clip_index=0,\n    filter_type=\"brightness\",\n    params=[\"level=0.8\"]\n)\n\n# Update brightness\nresult = filter_set_param(\n    track_id=0,\n    clip_index=0,\n    filter_index=0,\n    parameter=\"level\",\n    value=\"1.2\"\n)\n\n# List filters\nresult = filter_list(track_id=0, clip_index=0)\n```\n\n### Add Chapter Markers\n\n```python\nfrom kdenlive_mcp_server.server import (\n    project_new, bin_import_clip, timeline_add_track,\n    timeline_add_clip, guide_add, guide_list, project_save\n)\n\n# Setup\nresult = project_new(output_path=\"documentary.kdenlive-cli.json\", profile=\"4k30\")\nresult = bin_import_clip(clip_path=\"documentary.mp4\", name=\"Doc\", duration=900.0)\nresult = timeline_add_track(track_type=\"video\")\nresult = timeline_add_clip(clip_id=\"clip0\", track=0, position=0.0)\n\n# Add chapter markers\nresult = guide_add(position=60.0, label=\"Chapter 1: Introduction\", guide_type=\"chapter\")\nresult = guide_add(position=180.0, label=\"Chapter 2: Main Content\", guide_type=\"chapter\")\nresult = guide_add(position=300.0, label=\"Chapter 3: Conclusion\", guide_type=\"chapter\")\n\n# List guides\nresult = guide_list()\n\n# Save\nresult = project_save()\n```\n\n## Error Handling\n\nAll tools return consistent response formats:\n\n```python\n# Success\n{\n    \"success\": True,\n    \"data\": {...}\n}\n\n# Error\n{\n    \"success\": False,\n    \"error\": \"Error message describing the failure\"\n}\n```\n\n## Configuration\n\n### pyproject.toml\n\n```toml\n[project]\nname = \"kdenlive-mcp-server\"\nversion = \"0.1.0\"\ndescription = \"MCP server for Kdenlive video editing via cli-anything-kdenlive\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"mcp>=1.28.0\",\n    \"cli-anything-kdenlive>=1.0.0\",\n]\n\n[project.scripts]\nkdenlive-mcp = \"kdenlive_mcp_server.server:main\"\n\n[tool.uv.sources]\ncli-anything-kdenlive = { git = \"https://github.com/HKUDS/CLI-Anything.git\", subdirectory = \"kdenlive/agent-harness\" }\n```\n\n### uv.lock\n\nAuto-generated by `uv sync`. Contains locked dependency versions.\n\n## Dependencies\n\n- **mcp>=1.28.0**: FastMCP server framework for MCP protocol\n- **cli-anything-kdenlive @ git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=kdenlive/agent-harness**:\n  - CLI harness for Kdenlive video editing via melt\n  - Includes Gen 5 MLT XML format rewrite (PR #216)\n  - Provides Python API for project management\n\n## Troubleshooting\n\n### Kdenlive XML Compatibility Issues\n\nIf Kdenlive reports \"Version of the project file cannot be read\" or \"Timeline clip without bin reference found\":\n\n1. **Cause**: Using PyPI v1.0.0 (Gen 4 format) which lacks proper Kdenlive metadata\n2. **Fix**: The package now installs from GitHub HEAD with Gen 5 format that includes:\n   - `kdenlive:docproperties.version=\"1.1\"`\n   - Chain-based clip structure with `kdenlive:id` linking to main_bin\n   - Proper bin reference handling\n\n### Project Not Saving\n\nThe server auto-saves to disk after every mutation. If changes aren't persisting:\n\n1. Verify the project path is set via `project_new()` or `project_open()`\n2. Check that `session_status()` shows `has_project: true`\n3. Ensure the output directory is writable\n\n### FastMCP Server Not Starting\n\n1. Verify MCP version: `uv run python3 -c \"import mcp; print(mcp.__version__)\"`\n2. Check FastMCP: `uv run python3 -c \"from mcp.server.fastmcp import FastMCP; print('FastMCP OK')\"`\n3. Review logs for detailed error messages\n\n## Development\n\n### Testing\n\nRun the test suite:\n\n```bash\n# Run all integration tests\nuv run python3 test_integration.py\n\n# Test with zero-duration edge case\nuv run python3 test_edge_cases.py\n```\n\n### Code Style\n\nThe project follows PEP 8 style guidelines. Use `uv run ruff check .` to lint.\n\n### Adding New Tools\n\nTo add a new MCP tool:\n\n1. Add the tool function to `server.py` decorated with `@server.tool()`\n2. Import the corresponding CLI API module if needed\n3. Include comprehensive docstrings with Args and Returns sections\n4. Implement error handling with try/except\n5. Call `_save()` after mutations to persist changes\n\nExample:\n\n```python\n@server.tool()\ndef my_new_tool(param1: str, param2: int) -> dict[str, Any]:\n    \"\"\"Brief description of what the tool does.\n\n    Args:\n        param1: Description of param1.\n        param2: Description of param2.\n\n    Returns:\n        Success response format.\n    \"\"\"\n    err = _require_project()\n    if err:\n        return err\n\n    try:\n        # Do something with the project\n        result = some_api_function(param1, param2)\n        _save()\n        return _ok(result)\n    except Exception as e:\n        return _err(str(e))\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass: `uv run pytest`\n5. Submit a pull request\n\n## References\n\n- [CLI-Anything Kdenlive](https://github.com/HKUDS/CLI-Anything/tree/main/kdenlive/agent-harness)\n- [Kdenlive Documentation](https://kdenlive.org/en/doc/)\n- [FastMCP Documentation](https://github.com/jlowin/fastmcp)\n- [MLT XML Format](https://www.mltframework.org/docs/mltxml/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)",
  "bytes": 11897,
  "sha": "61a192b3a70261429a6cd59202111bfd1d2676016db6c6762f83e5959a09e087",
  "repo_slug": "va1bhav512/kdenlive-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_va1bhav512_kdenlive_mcp_server_9e9ef253/readme"
}