Shotcut MCP

Shotcut MCP

通过模型上下文协议进行本地视频编辑。

通过 AI 助手创建、编辑、验证、预览和渲染已保存的 Shotcut 项目。最终结果仍是可编辑的 .mlt 时间线，并通过事务性写入保护项目。

演示 · 快速开始 · 文档 · 网站

演示

通过 Shotcut MCP 编辑原生 Shotcut 时间线后生成的短 H.264 导出文件。

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

快速开始

你需要 Python 3.10+、Shotcut（推荐 26.8.1，捆绑的 MLT 为 7.41.0），以及支持本地 stdio 服务的 MCP 客户端。Shotcut 已包含所需的媒体工具、编解码器和滤镜。无需安装其他 Python 包。

1. 连接客户端

客户端	安装方式
Claude Desktop / 兼容 MCPB 的客户端	按照 MCPB 安装和更新指南操作。
Codex	克隆仓库并注册本地服务。
Claude Code	运行 /plugin marketplace add matrodrigs/shotcut-mcp，然后运行 /plugin install shotcut-mcp@matrodrigs 和 /reload-plugins。详情和手动设置。
其他 MCP 客户端	配置本地 stdio 服务。

安装指南包含适用于 Windows、macOS 和 Linux 的命令。运行服务无需执行 pip install。对于源码检出版本，指南还会介绍如何在连接 MCP 前，通过 scripts/shotcut_mcp_server.py --check 检查 Python 和 Shotcut。

2. 检查就绪状态

向助手提出以下请求：

运行 shotcut_status 和 shotcut_doctor。报告工具路径、版本以及未通过的运行时检查。

编辑前，请先解决未通过的运行时检查。请参阅故障排除了解恢复步骤。

3. 进行首次编辑

提供源文件夹和保存项目的目标位置，然后描述你的编辑需求：

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.

你可以用日常语言提出调整要求。字幕、质量分析、效果和交付相关内容，请参阅编辑工作流和示例提示词。

功能

• **编辑时间线：**处理轨道、片段、转场、变速、标题和字幕；在文件夹中查找源媒体，并在一次事务中应用最多 500 项操作。
• **检查结果：**检查源素材的质量和色彩，预览拟议的更改，并在导出前生成包含动态画面和音频的帧、联系表或短片。
• **渲染和交付：**导出完整项目、帧范围或命名标记；获取媒体文件以及本次渲染所用的确切可编辑项目。
• **本地处理：**使用已安装的 MLT 版本中的效果，并提供版本检查、验证、独立备份和原子文件替换。

支持的编辑操作请参阅完整功能参考。

事务安全

系统会根据已检查的版本核对编辑内容，使用 Melt 进行验证，并在原子替换已保存项目之前创建备份。未知 XML 会予以保留；有歧义的编辑会被拒绝。预览和渲染输出也会使用临时文件，并通过原子操作提升为正式文件。

每次渲染都使用不可变的项目快照，因此之后对时间线的编辑不会影响正在进行的导出。如果尚未请求导出，客户端会先确认输出路径、预设、范围和覆盖行为。明确提出的导出请求无需再次批准。

请阅读事务和恢复详情以及渲染行为。

局限性

• 服务会编辑已保存的项目文件；无法查看 Shotcut 中尚未保存的更改。请先等待 MCP 编辑完成，再在 GUI 中保存同一项目，然后重新检查。
• 可用的编解码器、滤镜、字体和质量分析器取决于本地安装情况。
• 某些含义不明确的转场、速度映射和跨轨道编辑会被拒绝。更改 FPS 会保留已识别的帧编号，而不会自动重新调整编辑时间。
• 默认情况下，网络资源和不安全的使用者属性会被拒绝。管理员可以通过运行时配置限制文件系统访问。

有关速度映射边界和恢复行为，请参阅所有局限性。

文档

指南	内容
安装	客户端设置、要求和就绪检查
工作流和示例	从编辑请求到视觉审查和交付
技术参考	功能、工具、预设、配置和安全性
行为规范	详细约定和兼容性边界
架构	模块职责和依赖方向

MCP 工具

MCP 工具目录列出了每个工具及其简要用途。客户端会在运行时获取完整的架构和操作指南；大多数用户完全可以通过自然语言提示词完成操作。

开发

有关通用质量门槛、真实集成测试、开发和发布流程，请参阅贡献指南；有关版本变更，请参阅更新日志；有关错误和功能请求，请参阅问题反馈；有关私密漏洞报告，请参阅安全。

许可证

本项目基于 MIT License 发布。这是一个独立的社区项目，与 Shotcut 或 MLT 项目无关联，也未获其认可。Shotcut 是其各自所有者的商标；MLT 是一个独立的开源多媒体框架。本仓库不包含 Shotcut 或 MLT 源代码。

_{由 matrodrigs 创建。}