<div align="center">

Shotcut MCP

Create, edit, validate, preview, and render saved Shotcut projects without operating the GUI.

Demo · Quick start · Features · Examples · Safety · Reference

</div>

Shotcut MCP is a local Model Context Protocol server for working with Shotcut projects stored as MLT XML. It gives an AI client structured tools for timeline editing while preserving Shotcut-specific project data.

It is designed for full edits of saved project files: build a multitrack timeline, apply effects, generate previews, and export the result without opening Shotcut. The Shotcut installation still provides Melt, FFmpeg, FFprobe, codecs, filters, and render services.

[!NOTE] This is an independent community project. It is not affiliated with or endorsed by Shotcut or the MLT project.

Demonstration

A short H.264 export created from a native Shotcut timeline edited through Shotcut MCP.

https://github.com/user-attachments/assets/c70f064f-17e7-403d-9bcf-689a9c616cdf

Why use it?

• Faster than GUI automation: up to 500 edits can be applied in one transaction.
• Safer than rewriting XML blindly: revisions, locks, validation, backups, and atomic replace protect the project being edited.
• Native project output: the result remains an editable .mlt project that opens in Shotcut.
• Local by default: the stdio server has no hosted service and uses only Python's standard library at runtime.
• Discoverable effects: filters, transitions, consumers, and links come from the user's installed MLT build instead of a fixed cloud catalog.

Features

Area	Capabilities
Tracks	Add, remove, rename, reorder, lock, hide, mute, and configure composition for video and audio tracks
Timeline	Add, duplicate, replace, split, and move media or generators using revision-scoped item references and transaction-local aliases; insert gaps, overwrite, remove ranges, trim, roll, slip, slide, and apply constant or variable speed
Transitions	Shotcut-compatible nested crossfades with selectable MLT video services and optional audio mixing
Effects	Animate clip pan, zoom, rotation, opacity, and volume with structured creative values; add, update, reorder, and remove native MLT filters on a clip, track, or project when lower-level control is needed
Generators	Color, dynamic text, tone, and noise
Project data	Profiles, semantic SDR/HLG/PQ workflows, notes, editable markers, subtitles, assisted hash-based relinking, and unknown XML preservation
Review	Compatibility doctor, source-quality and color analysis, inspection, read-only edit plans/diffs, MLT validation, preview batches, and atomic contact sheets
Export	Atomic chapter files and restart-resilient full/range/marker renders with ETA/history, safe presets, and hardware-encoder smoke detection
Recovery	Per-project isolated backups, revision conflict detection, backup listing, and validated restore

Quick start

MCPB package: compatible clients can install the latest packaged release.