Shotcut MCP

Local MCP server MIT licensed

Edit Shotcut timelines through MCP.

Create, inspect, and revise native .mlt projects with structured operations. Every edit stays local, validated, recoverable, and ready to reopen in Shotcut.

Get latest release Install from source
26
MCP tools
500
operations per transaction
0
runtime packages
Local
stdio transport

documentary.mlt

Ready
Request

Trim the pauses on V1, add an opening title, and render a preview at 00:27.

V2
Opening title
V1
Intro.movB-roll.mp4
A1

7 operations appliedrevision 7c92… → b18a…

Validated with Meltbackup retained

Native .mlt output 00:27
Works with saved Shotcut projects MLT 7.40 Python 3.10+ Windows, macOS, and Linux

Actual workflow

From intent to an editable project.

Shotcut MCP operates on the project format itself. It does not imitate mouse clicks or hide the changes behind a hosted service.

  1. 01

    Inspect the current project

    Read the profile, tracks, clips, filters, resources, and revision before making a change.

    inspect_project → revision
  2. 02

    Plan, then apply one transaction

    Preview a validated XML diff when useful, group related operations, and reject the edit if the project changed underneath it.

    edit_project × 1…500
  3. 03

    Validate and recheck

    Validate the temporary project with Melt, recheck the on-disk revision, create an isolated backup, then atomically replace the original.

    validate → backup → save
  4. 04

    Continue in Shotcut

    Preview, render, or open the native project for any final hands-on adjustment.

    render_preview → .png

Project safety

Edits fail safely or complete cleanly.

Revision checks prevent stale writes. Locks prevent concurrent MCP edits. Backups and atomic promotion keep a valid project on disk throughout the transaction.

Read the safety model
  1. 1
    Check revisionReject stale state
  2. 2
    Acquire lockOne writer at a time
  3. 3
    Edit in memoryPreserve unknown XML
  4. 4
    Validate with MeltTest the temporary file
  5. 5
    Backup and promoteAtomic replacement

Tool coverage

What the server can actually change.

Use specific MCP tools for discovery, editing, review, rendering, and recovery. Native MLT services remain available when you need lower-level control.

TIMELINE

Build and revise

  • Tracks, clip duplication/replacement, gaps, ripple, roll, slip, and slide
  • Constant speed, timewarp, and variable speed maps
  • Transitions, ordered filters, and keyframes
  • Titles, generators, editable markers, and subtitles
REVIEW

Inspect and recover

  • Structured project snapshots
  • Silence, black, freeze, interlace, and loudness analysis
  • Validated read-only edit plans and XML diffs
  • Batch previews and deterministic contact sheets
  • Assisted missing-media discovery and visual relink review
  • Revision history and validated restore
DELIVERY

Validate and render

  • Installed MLT service discovery
  • SDR, HLG, and PQ workflow diagnostics
  • Smoke-tested hardware encoder detection
  • Full, frame-range, and marker renders with ETA and history
  • Atomic Shotcut chapter-text exports
  • H.264, HEVC, AV1, ProRes, and more
See all 26 MCP tools

Installation

Choose the shortest path to a working server.

Shotcut MCP runs locally over stdio. It needs Python 3.10 or newer and a compatible Shotcut installation.

Recommended

MCPB-compatible clients

Install the packaged release.

Open the latest packaged release on GitHub and install it with your MCPB-compatible client.

View latest release

Windows PowerShell

Three source commands.

git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp
codex mcp add shotcut -- python "C:\path\to\shotcut-mcp\scripts\shotcut_mcp_server.py"
macOS or Linux commands 
git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp
codex mcp add shotcut -- python3 /absolute/path/to/shotcut-mcp/scripts/shotcut_mcp_server.py

Current compatibility target: Shotcut 26.6.25 with MLT 7.40.0.

Saved .mlt projects only. Unsaved GUI state remains outside the server boundary.

Common questions

Clear boundaries build trust.

Does Shotcut MCP control the Shotcut interface?

No. It edits saved MLT project files directly and uses the local Shotcut, Melt, FFmpeg, and FFprobe executables for validation, previews, and rendering.

Are my videos uploaded anywhere?

No. The server runs locally over stdio. Media and project files stay on your computer unless your chosen AI client has separate upload behavior. Network resources embedded in projects are denied by default.

Can I keep editing the result in Shotcut?

Yes. The output remains a native, editable .mlt project. Let the MCP finish its transaction before reopening or saving the same project in Shotcut.

Is it affiliated with Shotcut or MLT?

No. Shotcut MCP is an independent MIT-licensed community project and is not endorsed by Shotcut or the MLT project.

Ready when the project is

Start with a timeline you can always reopen.

Install Shotcut MCP, inspect an existing project, and make the first revision locally.

Get the latest release View source on GitHub