Local video editing through the Model Context Protocol.
Create, edit, validate, preview, and render saved [Shotcut](https://www.shotcut.org/) projects through your AI assistant. The result stays an editable `.mlt` timeline, with transactional writes that protect the project as you work. [Demonstration](#demonstration) · [Quick start](#quick-start) · [Documentation](#documentation) · [Website](https://matrodrigs.github.io/shotcut-mcp/) ## 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 ## Quick start You need **Python 3.10+**, **Shotcut** (recommended **26.8.1**, bundled MLT **7.41.0**), and an MCP client that supports local `stdio` servers. Shotcut includes the required media tools, codecs, and filters. No additional Python packages are required. ### 1. Connect your client | Client | Installation | | --- | --- | | Claude Desktop / MCPB-compatible client | Follow the [MCPB installation and update guide](docs/installation.md#claude-desktop-and-mcpb). | | Codex | Clone the repository and [register the local server](docs/installation.md#codex). | | Claude Code | Run `/plugin marketplace add matrodrigs/shotcut-mcp`, then `/plugin install shotcut-mcp@matrodrigs` and `/reload-plugins`. [Details and manual setup](docs/installation.md#claude-code). | | Other MCP client | Configure a [local stdio server](docs/installation.md#other-mcp-clients). | The [installation guide](docs/installation.md) includes commands for Windows, macOS, and Linux. No `pip install` is required to run the server. For a source checkout, the guide also shows how to check Python and Shotcut with `scripts/shotcut_mcp_server.py --check` before connecting MCP. ### 2. Check readiness Ask your assistant: > Run shotcut_status and shotcut_doctor. Report tool paths, versions, and failed runtime checks. Resolve failed runtime checks before editing. See [troubleshooting](docs/installation.md#troubleshooting-and-recovery) for recovery steps. ### 3. Make your first edit Provide the source folder and the destination for the saved project, then describe your edit: ```text 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. Generate a contact sheet so I can review the edit before exporting. ``` You can request adjustments in ordinary language. See the [editing workflow and example prompts](docs/workflows.md) for subtitles, quality analysis, effects, and delivery. ## Features - **Edit the timeline:** work with tracks, clips, transitions, speed changes, titles, and subtitles; discover source media in a folder and apply up to 500 operations in one transaction. - **Review the result:** inspect source quality and color, preview proposed changes, and generate frames, contact sheets, or short clips with motion and audio before exporting. - **Render and deliver:** export a full project, frame range, or named marker; receive the media and the exact editable project used for that render. - **Keep work local:** use effects from your installed MLT build, with revision checks, validation, isolated backups, and atomic file replacement. See the [full capability reference](docs/reference.md#features) for supported edit operations. ## Transactional safety Edits are checked against the inspected revision, validated with Melt, and backed up before atomically replacing the saved project. Unknown XML is preserved; ambiguous edits are rejected. Preview and render outputs also use temporary files and atomic promotion. Each render uses an immutable project snapshot, so later timeline edits cannot change a running export. If export was not already requested, the client confirms the output, preset, range, and overwrite behavior first. An explicit export request does not need a second approval. Read the [transaction and recovery details](docs/reference.md#transactional-safety) and [rendering behavior](docs/reference.md#rendering). ## Limitations - The server edits **saved project files**; it cannot see unsaved changes in Shotcut. Let an MCP edit finish before saving the same project in the GUI, then inspect it again. - Available codecs, filters, fonts, and quality analyzers depend on your local installation. - Some ambiguous transitions, speed maps, and cross-track edits are rejected. Changing FPS preserves recognized frame numbers rather than automatically retiming the edit. - Network resources and unsafe consumer properties are denied by default. Administrators can restrict filesystem access through the [runtime configuration](docs/reference.md#configuration). See [all limitations](docs/reference.md#limitations) for speed-map boundaries and recovery behavior. ## Documentation | Guide | What you will find | | --- | --- | | [Installation](docs/installation.md) | Client setup, requirements, and readiness checks | | [Workflow and examples](docs/workflows.md) | From an edit request to visual review and delivery | | [Technical reference](docs/reference.md) | Capabilities, tools, presets, configuration, and safety | | [Behavioral specification](docs/spec.md) | Detailed contracts and compatibility boundaries | | [Architecture](docs/architecture.md) | Module responsibilities and dependency direction | ### MCP tools The [MCP tool catalog](docs/reference.md#mcp-tools) lists every tool with a concise purpose. Clients receive full schemas and operation guidance at runtime; most users can work entirely through natural-language prompts. ## Development See [Contributing](CONTRIBUTING.md) for the shared quality gate, real integration tests, development, and release procedures, [Changelog](CHANGELOG.md) for release changes, [Issues](https://github.com/matrodrigs/shotcut-mcp/issues) for bugs and feature requests, and [Security](SECURITY.md) for private vulnerability reporting. ## License Released under the [MIT License](LICENSE). This is an independent community project, not affiliated with or endorsed by Shotcut or the MLT project. 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. Created by matrodrigs.