Shotcut MCP

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

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

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.

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

Related MCP server: OpenCut Controller

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

Quick start

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

Requirements

• Python 3.10 or newer

• Shotcut 26.6.25, with MLT 7.40.0 serialization in the compatible 7.40.x family

• Codex CLI, Claude Code, or another MCP client that supports local stdio servers

Additional compatibility and runtime behavior, including progress, MLT startup, and RNNoise checks, are documented in the behavioral specification.

Choose your client

Codex

Clone the repository. No pip install is required.

git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp

Register the server using an absolute path to the checked-out script.

Windows PowerShell

codex mcp add shotcut -- python "C:\path\to\shotcut-mcp\scripts\shotcut_mcp_server.py"

macOS or Linux

codex mcp add shotcut -- python3 /absolute/path/to/shotcut-mcp/scripts/shotcut_mcp_server.py

Claude Code

Run these commands inside Claude Code. No repository clone is required.

/plugin marketplace add matrodrigs/shotcut-mcp
/plugin install shotcut-mcp@matrodrigs

Run /reload-plugins to activate the plugin without restarting Claude Code.

Clone the repository. No pip install is required.

git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp

Then register the server directly using an absolute path to the checked-out script.

Windows PowerShell

claude mcp add --transport stdio --scope user shotcut -- python "C:\path\to\shotcut-mcp\scripts\shotcut_mcp_server.py"

macOS or Linux

claude mcp add --transport stdio --scope user shotcut -- python3 /absolute/path/to/shotcut-mcp/scripts/shotcut_mcp_server.py

From a source checkout, Claude Code can also use the checked-in .mcp.json as project-scoped configuration when it is started from the repository root. Review and approve the server when prompted.

Other MCP clients

Clone the repository. No pip install is required.

git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp

Configure a local stdio server with these values:

The .codex-plugin and .claude-plugin manifests are thin client adapters. The Claude marketplace entry only adds discovery and installation. Every route starts the same dependency-free Python server; the tools, schemas, and project-safety behavior do not fork by client.

Restart the MCP client or open a new task after registration.

Verify the installation

Ask your MCP client:

Check whether Shotcut MCP is ready and report the detected Shotcut, Melt, FFmpeg, and FFprobe versions.

A healthy setup reports the discovered paths, versions, repository state, RNNoise availability, and active path policy. If anything is missing, the response should explain what needs attention.

Example prompts

Create a 1920×1080, 30 fps Shotcut project from every video in this folder.
Put narration on A1, add 12-frame crossfades, and save it as documentary.mlt.

Inspect documentary.mlt, remove the pauses between clips on V1, add title cards,
add a slow push-in with smooth audio and video fades, generate preview frames at each
section boundary, and keep the project editable.

Add these Portuguese subtitles, burn them in using a readable bottom-center style,
then render an H.264 web export. Monitor the job until it completes.

Analyze interview.mov for silence, frozen or black video, interlacing, and EBU R128 loudness.
Return the measurements before proposing any cleanup edits.

Inspect documentary.mlt, export its point markers as chapters.txt, then render only the range
marker named "Trailer" with the H.264 web preset.

Recommended workflow

Describe the result you want in ordinary language. The MCP client receives tool-specific guidance at runtime, so you do not need to know individual tool names or request schemas.

1. Start by asking the client to check that Shotcut MCP and the local media tools are ready.

2. Share the saved .mlt project and source media you want to use, then describe the intended edit.

3. For cleanup work, ask for measurements such as silence, black frames, freezes, interlacing, or loudness before deciding what to change.

4. For a large or sensitive edit, ask to review the proposed changes before they are applied.

5. Review representative frames or a contact sheet, and request adjustments if needed.

6. Export the full project or a named range, then ask the client to monitor the render to completion.

Let an MCP edit finish before saving the same project from the Shotcut GUI. After manual adjustments, save in Shotcut and ask the client to inspect the project again before continuing.

Transactional safety

flowchart LR
    A["Inspect project"] --> B["Check revision and acquire lock"]
    B --> C["Apply batch in memory"]
    C --> D["Write temporary MLT XML"]
    D --> E["Validate with Melt"]
    E --> F["Recheck on-disk revision"]
    F --> G["Create isolated backup"]
    G --> H["Atomic replace"]

Every project edit uses the following safeguards:

• SHA-256 revision checks and a per-project .shotcut-mcp.lock

• Temporary-file MLT validation, an on-disk revision recheck, an isolated backup, and atomic replace

• Retention of the 20 most recent backups in a project-specific namespace

• Preservation of unknown XML and rejection of ambiguous transitions or basename relinks

• One canonical allowed-root/network policy for tool paths and embedded project resources

• Bounded MCP input/output, project candidates (128 MiB by default), process output, render logs, history, searches, and previews

Existing preview and render outputs are also protected: output is written to a temporary sibling, the target is checked again for concurrent changes, and promotion is atomic. A dedicated render supervisor owns completion and cancellation independently of the MCP stdio process.

MCP tools

Most users can work entirely through natural-language prompts. This reference is for client authors, integrators, and anyone who wants to understand the available tool surface.

Clients receive full JSON schemas, operation examples, revision requirements, stable item-reference guidance, and animation contracts at runtime. Integrators can consult the behavioral specification; the published tool schemas remain the source of truth for request parameters.

Rendering

Ask the client to render the complete project, a precise frame range, or a named range marker. Renders run under a durable supervisor, so progress can still be checked or cancellation requested after the MCP client restarts.

HDR presets use verified 10-bit software encoders; codec and hardware availability still depend on the local build. Preview and final outputs are written transactionally and replace their destination only after the new file completes successfully.

Configuration

Common Shotcut installations are detected automatically, so most users can skip this section. Administrators and client integrators can override discovery or tighten runtime policy when needed:

Network resources and unsafe consumer properties are denied by default. These variables are administrator policies: tools cannot override them per request. shotcut_status and shotcut_doctor report the active policy.

Development

Runtime code uses only the Python standard library. Run the local quality gate with:

python -m pip install -r requirements-dev.txt
python -B scripts/check_ci.py all

Enable the versioned pre-push gate once per clone so the same command runs before changes reach GitHub:

git config core.hooksPath .githooks

Real Shotcut integration is opt-in through SHOTCUT_MCP_INTEGRATION=1. See CONTRIBUTING.md for development and verified release procedures, and CHANGELOG.md for release changes. Use GitHub Issues for bugs or feature requests and SECURITY.md for private vulnerability reporting.

Limitations

• The MCP edits the latest project state saved to disk; it cannot see unsaved GUI changes.

• Unknown MLT XML is preserved, but edits are rejected when a target cannot be identified safely.

• Third-party filters, GPU/OpenGL services, codecs, and fonts vary by Shotcut installation.

• Quality analysis depends on filters present in the installed FFmpeg build. Checks run independently and report unavailable or not_applicable instead of failing the whole analysis.

• Speed maps accept wholly forward or wholly reverse non-zero ramps. Zero-crossing ramps and third-party/ambiguous chain links remain rejected.

• Ripple trim can affect only the target track or every unlocked track. Locked tracks are left unchanged, and a cross-track removal that intersects a transition is rejected rather than rewired speculatively.

• Changing project FPS preserves recognized timeline and marker frame numbers; it does not automatically retime the creative edit.

• If the dedicated render supervisor itself is forcibly killed while Melt survives, the job is reported as orphaned and its temporary output is retained rather than guessed at or promoted.

License

Released under the MIT License.

Shotcut is a trademark of its respective owner. MLT is an independent open-source multimedia framework. This repository contains no Shotcut or MLT source code.