Shotcut MCP

shotcut-mcp

通过 Shotcut 的引擎 MLT 编辑视频的 MCP 服务，无需 GUI。Agent 可以创建项目、添加和修剪片段、拆分、移动和删除片段、应用滤镜、添加标题和交叉淡化、读取时间线，并使用 melt 渲染。

输出是原生 Shotcut .mlt 项目，而不是受限的视频文件。在 Shotcut 中打开 Agent 剪辑的版本，继续手动编辑。

要求

• Python 3.11+
• 将 MLT melt 添加到 PATH，或将 MELT_BIN 设置为其完整路径。安装 Shotcut 时会包含 melt。
  • Linux：sudo apt install melt
  • macOS：安装 Shotcut，然后将 MELT_BIN=/Applications/Shotcut.app/Contents/MacOS/melt
  • Windows：安装 Shotcut，然后将 MELT_BIN 设置为 Shotcut 文件夹中的 melt.exe。CI 尚未涵盖 Windows 渲染。
• 将 ffprobe（来自 FFmpeg）添加到 PATH，以读取片段时长并检查渲染结果。可通过 FFPROBE_BIN 覆盖。

安装

使用 uv 即可运行，无需安装：

uvx shotcut-mcp

也可以使用 pip 安装：

pip install shotcut-mcp
shotcut-mcp

该服务通过 stdio 与 MCP 通信。

与 goose 搭配使用

goose Desktop 或 CLI

1. 运行 goose configure，选择 Add Extension，然后选择 Command-line Extension。
2. 名称：shotcut
3. 命令：uvx shotcut-mcp
4. 超时：600 秒或更长。渲染所需时间比 goose 的默认值长。
5. 添加环境变量 SHOTCUT_MCP_WORKDIR；如果 melt 不在 PATH 中，还需添加 MELT_BIN。

config.yaml

将以下内容添加到 ~/.config/goose/config.yaml：

extensions:
  shotcut:
    enabled: true
    type: stdio
    name: shotcut
    cmd: uvx
    args:
      - shotcut-mcp
    envs:
      SHOTCUT_MCP_WORKDIR: /path/to/your/projects
    timeout: 600

然后向 goose 提出类似这样的请求：“使用 clip1.mp4 和 clip2.mp4 创建一个名为 promo 的项目，保留每个片段的前 5 秒，在两者之间添加交叉淡化，添加标题 ‘Launch day’ 并渲染。”

与其他 MCP 客户端搭配使用

任何可运行 stdio 服务的 MCP 客户端都适用。例如，Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "shotcut": {
      "command": "uvx",
      "args": ["shotcut-mcp"],
      "env": { "SHOTCUT_MCP_WORKDIR": "/path/to/your/projects" }
    }
  }
}

配置

变量	默认值	作用
SHOTCUT_MCP_WORKDIR	~/shotcut-mcp-projects	保存 .mlt 项目及其状态文件的位置
MELT_BIN	melt	用于渲染的 melt 二进制文件路径
FFPROBE_BIN	ffprobe	ffprobe 的路径，用于读取源文件时长

工具

工具	作用
create_project	使用指定帧尺寸和帧率创建新项目
add_clip	将源视频的一段添加到时间线末尾。返回片段 ID
trim_clip	更改片段源文件的入点和出点
remove_clip	涟漪删除一个片段
move_clip	将片段移动到时间线上的新位置
split_clip	在片段内部的指定位置将其拆分为两段
remove_segment	涟漪删除一段时间线内容
append_text_overlay	在指定的起止时间之间，在时间线上叠加文本标题
apply_filter	对片段应用 brightness、volume、crop、fadeInBrightness、fadeOutBrightness、fadeInAudio 或 fadeOutAudio
set_transition	在两个相邻片段之间交叉淡化视频和音频
get_timeline	返回完整剪辑信息：片段、源文件入点和出点、时间线位置、滤镜、转场和标题
project_info	返回项目摘要元数据
render	使用 melt 将项目渲染为视频文件
list_projects	列出工作目录中的项目

片段 ID 在多次调用之间保持稳定。编辑状态保存在每个 .mlt 旁边的 .state.json 文件中，每次更改后都会根据该文件重新生成 .mlt。

当前限制

• 仅支持一个视频轨道。计划支持多轨视频和音频。
• 在 Shotcut GUI 中手动进行的编辑会在下一次调用工具时被覆盖。计划支持安全往返编辑。
• set_transition 的 style 选项会被接受，但目前渲染时只会生成溶解效果。

开发

pip install -e ".[dev]"
pytest

未安装 melt 时会跳过渲染测试。

许可证

MIT