内容
<div align="center">
# Shotcut MCP
**在无需操作 GUI 的情况下，创建、编辑、验证、预览和渲染已保存的 Shotcut 项目。**
[](LICENSE)
[](https://www.python.org/)
[](https://www.shotcut.org/)
[](https://modelcontextprotocol.io/)
[](https://registry.modelcontextprotocol.io/?search=io.github.matrodrigs%2Fshotcut-mcp)
[](https://matrodrigs.github.io/shotcut-mcp/)
[快速开始](#快速开始) · [功能](#功能) · [工具](#MCP-工具) · [安全性](#事务安全性) · [开发](#开发)
</div>
> **下载：**MCPB 兼容客户端可以从 [最新的 GitHub 发布版本](https://github.com/matrodrigs/shotcut-mcp/releases/latest) 安装打包的服务器。
Shotcut MCP 是一个本地 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，用于处理存储为 MLT XML 的 Shotcut 项目。它为 AI 客户端提供了结构化的时间线编辑工具，同时保留了 Shotcut 特有的项目数据。
它的设计用于完全编辑 **已保存的项目文件**：构建多轨时间线，应用效果，生成预览并导出结果，而无需打开 Shotcut。Shotcut 安装仍然提供 Melt、FFmpeg、FFprobe、编解码器、滤镜和渲染服务。
> [!NOTE]
> 这是一个独立的社区项目。它与 Shotcut 或 MLT 项目无关，也未获得它们的认可。
## 为什么使用它？
- **比 GUI 自动化更快：** 最多可以在一次事务中应用 500 个编辑。
- **比盲目重写 XML 更安全：** 修订、锁定、验证、备份和原子替换保护正在编辑的项目。
- **原生项目输出：** 结果仍然是一个可编辑的 `.mlt` 项目，可以在 Shotcut 中打开。
- **默认本地：** stdio 服务器没有托管服务，运行时仅使用 Python 标准库。
- **可发现的效果：** 滤镜、过渡和消费者来自用户安装的 MLT 版本，而不是固定的云目录。
## 功能
| 领域 | 能力 |
| --- | --- |
| 轨道 | 添加、删除、重命名、重新排序、锁定、隐藏、静音和配置视频和音频轨道的合成 |
| 时间线 | 添加媒体或生成器、插入间隙、覆盖、波纹删除、修剪、分割、移动和删除范围 |
| 过渡 | Shotcut 兼容的嵌套淡入淡出，具有可选的 MLT 视频服务和可选的音频混合 |
| 效果 | 在剪辑、轨道或项目上添加、更新和删除 MLT 滤镜；支持原生关键帧属性字符串 |
| 生成器 | 颜色、动态文本、音调和噪声 |
| 项目数据 | 配置文件、注释、标记、字幕、媒体重新链接和未知 XML 保留 |
| 审查 | 项目检查、MLT 验证和帧精确 PNG 预览 |
| 导出 | H.264、HEVC、AV1、ProRes、DNxHD、FLAC 和 MP3 的监控后台渲染 |
| 恢复 | 时间戳备份、修订冲突检测、备份列表和验证恢复 |
## 快速开始
### 要求
- Python 3.10 或更高版本
- Shotcut 26.2.26，或提供 MLT 7.37.x 的兼容安装
- Codex CLI 或另一个支持本地 stdio 服务器的 MCP 客户端
当前兼容性目标是 Shotcut **26.2.26** 和 MLT **7.37.0**。集成套件在 Windows 上进行了测试；可执行文件发现还支持 `PATH` 和常见 macOS 位置上可用的二进制文件。
### 1. 克隆存储库
```bash
git clone https://github.com/matrodrigs/shotcut-mcp.git
cd shotcut-mcp
```
不需要 `pip install`。
### 2. 注册 MCP 服务器
使用服务器脚本的绝对路径。
**Windows PowerShell**
```powershell
codex mcp add shotcut -- python "C:\path\to\shotcut-mcp\scripts\shotcut_mcp_server.py"
```
**macOS 或 Linux**
```bash
codex mcp add shotcut -- python3 /absolute/path/to/shotcut-mcp/scripts/shotcut_mcp_server.py
```
注册后重启 MCP 客户端或打开新任务。
### 3. 检查安装
询问您的 MCP 客户端：
> 检查 Shotcut MCP 是否就绪，并报告检测到的 Shotcut、Melt、FFmpeg 和 FFprobe 版本。
客户端应调用 `shotcut_status` 并返回发现的可执行文件路径和版本。
## 示例提示
```text
为此文件夹中的每个视频创建一个 1920×1080、30 fps 的 Shotcut 项目。
将旁白放在 A1 上，添加 12 帧淡入淡出，并将其保存为 documentary.mlt。
```
```text
检查 documentary.mlt，删除 V1 上剪辑之间的暂停，添加标题卡，
在每个部分边界生成预览帧，并保持项目可编辑。
```
```text
添加这些葡萄牙语字幕，使用易读的底部居中样式将其刻录，
然后渲染 H.264 网页导出。监控作业直到完成。
```
## 推荐的工作流程
1. 调用 `shotcut_status` 以验证本地工具链。
2. 创建项目或调用 `inspect_project` 以获取其 SHA-256 `revision`。
3. 读取 `shotcut_capabilities` 以获取操作参数。
4. 通过 `edit_project` 一起提交相关更改，传递修订版作为 `expected_revision`。
5. 生成一个或多个预览并审查结构化的项目快照。
6. 启动渲染并轮询 `render_status` 直到完成。
在 MCP 编辑项目时，请勿使用 Shotcut GUI 保存同一项目。对于手动视觉调整，让 MCP 完成一个批次，在 Shotcut 中保存，检查新修订版，然后继续。
## 事务安全性
```mermaid
flowchart LR
A["检查项目"] --> B["检查修订版并获取锁"]
B --> C["在内存中应用批次"]
C --> D["写入临时 MLT XML"]
D --> E["与 Melt 验证"]
E --> F["创建时间戳备份"]
F --> G["原子替换"]
```
每个项目编辑都使用以下安全措施：
- 具有 SHA-256 项目修订版的乐观并发
- 一个项目 `.shotcut-mcp.lock` 文件
- 临时项目在替换前通过 Melt 验证
- `.shotcut-mcp/backups` 中的时间戳备份
- 验证成功后仅原子替换
- 每个项目保留 20 个最近的备份
- 保留未知的 XML 元素、属性和属性
- 拒绝模糊的第三方过渡布局和模糊的基本名称重新链接
现有的渲染输出也受到保护：新渲染写入临时同级文件，仅在 Melt 成功完成后原子促进。
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `shotcut_status` | 发现 Shotcut、Melt、FFmpeg 和 FFprobe 并报告版本 |
| `shotcut_capabilities` | 返回编辑操作、渲染预设、兼容性和工作流程指导 |
| `probe_media` | 检查流、编解码器、尺寸、帧率、音频和持续时间 |
| `inspect_project` | 返回修订版、配置文件、轨道、项目、滤镜、标记、字幕和资源 |
| `create_project` | 创建兼容 Shotcut 的多轨 MLT 项目 |
| `edit_project` | 在一个验证的交易中应用最多 500 个时间线操作 |
| `list_mlt_services` | 列出本地可用的 MLT 滤镜、过渡、生产者或消费者 |
| `describe_mlt_service` | 返回已安装的 MLT 服务的元数据 |
| `validate_project` | 解析项目并使用 Melt 验证 |
| `render_preview` | 将选定的帧渲染为 PNG |
| `open_in_shotcut` | 在 Shotcut GUI 中打开项目或媒体路径 |
| `start_render` | 启动监控后台渲染 |
| `render_status` | 返回渲染状态、进度、输出信息和日志尾部 |
| `cancel_render` | 停止在当前 MCP 会话中启动的渲染 |
| `list_project_backups` | 列出保留的项目备份和修订版 |
| `restore_project_backup` | 验证并原子恢复选定的备份 |
### `edit_project` 操作
| 组 | 操作 |
| --- | --- |
| 轨道 | `add_track`、`remove_track`、`update_track`、`move_track` |
| 媒体和生成器 | `add_clip`、`add_generator`、`relink_media` |
| 时间线 | `remove_item`、`trim_item`、`split_item`、`move_item`、`insert_gap`、`remove_range` |
| 过渡 | `add_transition`、`remove_transition` |
| 滤镜 | `add_filter`、`update_filter`、`remove_filter` |
| 元数据 | `set_notes`、`add_marker`、`remove_marker`、`set_profile` |
| 字幕 | `set_subtitle_track`、`remove_subtitle_track` |
`shotcut_capabilities` 是每个操作的接受字段的运行时真相来源。
### 交易示例
```json
{
"project_path": "C:/video/project.mlt",
"expected_revision": "<由 inspect_project 返回的修订版>",
"operations": [
{
"op": "add_track",
"kind": "video",
"name": "Titles"
},
{
"op": "add_generator",
"track": "Titles",
"generator": "text",
"text": "Opening title",
"duration_frames": 90,
"position_frame": 0,
"mode": "overwrite"
},
{
"op": "add_marker",
"start_frame": 0,
"text": "Intro",
"color": "#00A0FF"
}
]
}
```
## 渲染
为常见的交付和中间格式提供内置预设：
- `h264-high`
- `h264-web`
- `hevc`
- `av1`
- `prores`
- `dnxhd`
- `audio-flac`
- `audio-mp3`
高级调用者可以提供验证的原生 `avformat` 消费者属性。编解码器和硬件可用性仍取决于本地 Shotcut/FFmpeg 构建。
## 配置
自动检测常见的 Shotcut 安装。必要时覆盖发现：
| 环境变量 | 可执行文件 |
| --- | --- |
| `SHOTCUT_PATH` | Shotcut 应用程序 |
| `SHOTCUT_MELT_PATH` | Melt 可执行文件 |
| `SHOTCUT_FFMPEG_PATH` | FFmpeg 可执行文件 |
| `SHOTCUT_FFPROBE_PATH` | FFprobe 可执行文件 |
## 项目结构
```text
shotcut-mcp/
├── .codex-plugin/plugin.json # Codex 插件清单
├── .mcp.json # 捆绑的 MCP 服务器配置
├── scripts/ # 无依赖的 stdio 入口点
├── shotcut_mcp/
│ ├── platform.py # 可执行文件发现和 MLT 集成
│ ├── project.py # 事务性 MLT 项目模型
│ ├── render.py # 后台渲染作业
│ ├── server.py # JSON-RPC/MCP stdio 传输
│ └── tools.py # 工具模式和处理程序
├── tests/ # 单元测试和真实 Shotcut 集成测试
└── docs/spec.md # 行为和兼容性规范
```
## 开发
运行时代码仅使用 Python 标准库。开发检查使用 Ruff 和 Mypy。
```bash
python -m ruff format --check shotcut_mcp scripts tests
python -m ruff check shotcut_mcp scripts tests
python -m mypy shotcut_mcp scripts tests
python -m unittest discover -s tests -v
```
显式运行真实 Shotcut 集成测试：
**Windows PowerShell**
```powershell
$env:SHOTCUT_MCP_INTEGRATION = "1"
python -m unittest discover -s tests -v
```
**macOS 或 Linux**
```bash
SHOTCUT_MCP_INTEGRATION=1 python -m unittest discover -s tests -v
```
集成测试创建媒体，构建带有淡入淡出和标题轨道的两个剪辑时间线，通过 Melt 验证它，渲染 PNG 预览并导出 H.264 视频。
在打开拉取请求之前，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。对于错误或功能请求，请使用 [GitHub Issues](https://github.com/matrodrigs/shotcut-mcp/issues)。
## 限制
- MCP 编辑磁盘上保存的最新项目状态；它看不到未保存的 GUI 更改。
- 未知 MLT XML 被保留，但如果无法安全识别目标，则拒绝编辑。
- 第三方滤镜、GPU/OpenGL 服务、编解码器和字体因 Shotcut 安装而异。
- 更改项目 FPS 保留识别的时间线和标记帧号；它不会自动重新计时创意编辑。
- 通过 MCP 服务器重启分离的渲染可以在 OS 级别继续，但不能再由重启的服务器安全取消。
## 许可证
在 [MIT License](LICENSE) 下发布。
Shotcut 是其各自所有者的商标。MLT 是一个独立的开源多媒体框架。本存储库不包含任何 Shotcut 或 MLT 源代码。
