# Shotcut MCP

<p><samp>Local video editing through the Model Context Protocol.</samp></p>

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.

<sub>Created by <a href="https://github.com/matrodrigs">matrodrigs</a>.</sub>