videoworker

videoworker MCP

为你的 AI Agent 配备媒体工作流：上传、选择预设、保存结果。

基于 MIT 许可、通过本地 stdio 连接 videoworker 视频、音频和图像处理 API 的 MCP 连接器。日常导出可使用带版本号的预设， 自定义编辑则可使用标准 FFmpeg 参数。处理由我们的工作器完成； 无需在本地安装 FFmpeg。

免费开始使用 · 托管 MCP · REST API · 版本发布 · 已列入 Glama

你的 Agent 能做什么？

任务	预设	结果
修剪并调整视频尺寸	web-mp4 v1	适用于 Web 的 H.264/AAC MP4
提取音频	audio-mp3 v1	MP3 音频
截取视频帧	thumbnail-jpg v1	JPEG 缩略图
制作短预览	gif-preview v1	动态 GIF
烧录字幕	subtitles-burn-mp4 v1	渲染了 SRT/VTT 文本的 MP4
添加字幕轨道	subtitles-track-mp4 v1	带可切换字幕轨道的 MP4

字幕预设需要两个输入：先是视频，然后是你自己的 .srt 或 .vtt 文件 （最大 2 MiB）。它们不会转录或翻译。

使用 list_presets 查看参数和所需输入数量，然后按显示顺序提供已上传文件的 ID，并通过 明确的版本调用 run_preset。对于多文件编辑、叠加层或自定义 滤镜，create_job 接受自定义 FFmpeg 参数。两种任务都可通过相同的工具和账户额度进行跟踪、取消和下载。

已签名的任务 Webhook 会在任务完成时通知你自己的 HTTPS 端点；该功能已在 videoworker.dev 上线。通过托管 MCP、REST 和此源代码仓库，可为每个任务选择端点（指南，附带持久接收器示例）；已发布的 v0.2.0 wheel 暂不包含该参数。 预设是否可用始终以服务端目录为准，因此请使用 list_presets 检查，而不要假定某个预设存在。

选择连接方式

	本地连接器 — 此仓库	托管 MCP
适用场景	上传和下载本地文件	无需安装 Python 即可连接
传输方式	stdio	可流式 HTTP
登录方式	私有文件中的限定范围 API 密钥	浏览器登录和 OAuth 授权
本地文件访问	可访问所选文件夹中指定的媒体文件	无；需先通过 Web 或 REST 上传
设置方式	见下方快速入门	托管设置指南

两种方式使用相同的账户和额度。该连接器是免费软件；托管处理服务遵循当前方案和限制。 免费账户每月可获得少量额度。请查看定价页面，了解 Starter 上线优惠及其适用情况；使用 Free 方案无需试用。

快速入门

1. 安装 — 无需检出代码或使用 Git

需要 Python 3.12 或更高版本。安装带版本号的发行 wheel：

python -m pip install "https://github.com/AzadKurt/videoworker-mcp/releases/download/v0.2.0/videoworker_mcp-0.2.0-py3-none-any.whl"
python -m videoworker_mcp --version

在 Windows 上，如有需要，请用 py -3.12 替代 python。在 macOS/Linux 上， 命令可能是 python3。在 MCP 配置中使用同一个 Python 安装。运行以下命令打印完整路径：

python -c "import sys; print(sys.executable)"

如果已安装 Git，也可以使用以下方式：

python -m pip install "git+https://github.com/AzadKurt/[email protected]"

此软件包尚未发布到 PyPI。pip install videoworker-mcp 不是此版本的安装命令。

2. 创建工作区和私钥文件

登录你的工作区。在 API keys 下，创建一个密钥，并为全部十个工具授予 usage:read、files:write、jobs:read、jobs:write 和 outputs:read 权限。将密钥保存为纯文本文件，并确保只有你的用户可以访问该文件。在 macOS/Linux 上：chmod 600 /absolute/path/to/key。在 Windows 上，将文件保存在你的用户配置文件中，并限制文件权限，确保只有你可以访问。

创建 uploads 和 downloads 文件夹。两个文件夹都必须存在，并使用绝对路径。uploads 中只放经授权的媒体；密钥文件应保存在其他位置。切勿将密钥粘贴到聊天中或共享的客户端配置中。

3. 添加客户端配置

将 Python 和文件夹路径替换为你自己的路径。将条目合并到现有配置中，保留其他服务。配置值是路径，不是密钥。保存后重启或重新加载客户端。

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.videoworker]
command = "/absolute/path/to/python"
args = ["-m", "videoworker_mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 960

[mcp_servers.videoworker.env]
VIDEO_WORKER_API_KEY_FILE = "/absolute/path/to/videoworker.key"
VIDEO_WORKER_UPLOAD_ROOT = "/absolute/path/to/uploads"
VIDEO_WORKER_DOWNLOAD_ROOT = "/absolute/path/to/downloads"

Windows 路径可以使用正斜杠，例如 C:/Users/YOU/media/uploads。可直接编辑的配置：Windows / macOS 和 Linux。如果也使用托管连接，请将其命名为 videoworker_remote。

Claude Desktop

打开 Settings → Developer → Edit Config 并合并：

{
  "mcpServers": {
    "videoworker": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "videoworker_mcp"],
      "env": {
        "VIDEO_WORKER_API_KEY_FILE": "/absolute/path/to/videoworker.key",
        "VIDEO_WORKER_UPLOAD_ROOT": "/absolute/path/to/uploads",
        "VIDEO_WORKER_DOWNLOAD_ROOT": "/absolute/path/to/downloads"
      }
    }
  }
}

可直接编辑的配置：Windows / macOS 和 Linux。

Cursor

在 ~/.cursor/mcp.json（全局配置）或 .cursor/mcp.json（项目配置）中使用相同的 JSON 结构。在 Cursor 的 MCP 设置中启用该服务。可直接编辑的配置：Windows / macOS 和 Linux。

示例遵循文档中说明的 stdio 配置格式。我们已测试真实 MCP SDK 的发现功能；这并不表示我们手动测试过所有桌面应用或版本。

4. 试运行一个小任务

将一个较小的 clip.mp4 放入 uploads 文件夹，并向你的 Agent 发送请求：

检查我的 videoworker 额度，并先列出预设。我授权从已配置的 uploads 文件夹上传 clip.mp4。使用 web-mp4 version 1 导出前一秒，格式为 MP4，max_width 为 640，处理时限为 10 秒。创建一个任务。保留其 request_id 以供重试；每次状态检查之间至少等待一秒，并将成功结果保存到我的 downloads 文件夹。不要删除任何内容。

流程：get_usage → list_presets → upload_file → run_preset → get_job → download_result。参见预设参数：替换输入文件 ID，并为每个计划创建的任务生成新的 UUID。想使用原始命令？请使用 create_job，并传入这些示例任务参数。

多个输入

工作流示例涵盖拼接片段、添加图像/徽标以及替换配乐。每个示例都包含输入顺序、行为说明和可直接编辑的 MCP JSON 文件。同样的示例也展示在网站上，并提供 REST 和 MCP 的复制按钮。

版本化预设

对于支持 GET /v1/presets 的服务，使用 list_presets 发现经过验证的参数、固定版本和输出文件名。然后使用上传文件 ID、明确指定的版本、参数、处理时长上限和自选 UUID 调用 run_preset。MCP 参数示例 可将视频裁剪并调整尺寸为 H.264/AAC MP4。目录中的其他条目可提取 MP3、生成 JPEG 缩略图或渲染短 GIF。

适用相同的普通任务配额、所有权和存储规则。超时设置预留的是处理时长上限，而非片段时长。每秒调用 get_job 不超过一次，并在过期前下载。48 小时内重试时，请使用完全相同的请求和 UUID；切勿自动重新提交未收到回复的请求。默认值和编码行为由版本固定。不保证输出文件更小。

版本 0.2.0 新增了这些工具，并要求服务支持预设。 presets_unsupported 表示服务没有目录； presets_unsupported 也表示缺少执行路由； preset_not_found 表示未知的 ID/版本，input_unavailable 表示所属上传文件缺失或已过期。未知的 404 响应格式仍返回 preset_unavailable。任何情况下都不会静默回退到其他任务。由于 REST 元数据目录有意设为公开，列出预设前会先使用同一个密钥检查所属任务读取端点。

工具

工具	用途	API 密钥范围
get_usage	配额、预留额度和存储	usage:read
list_jobs	最近的所属任务	jobs:read
list_presets	版本化任务、参数和默认值	jobs:read
run_preset	使用稳定重试 UUID 执行单个预设任务	jobs:write
upload_file	上传已获授权的本地媒体	files:write
create_job	使用稳定重试 UUID 创建 FFmpeg 任务	jobs:write
get_job	任务状态和输出元数据	jobs:read
download_result	将输出保存到新的本地文件	jobs:read、outputs:read
cancel_job	请求取消；确认任务已终止	jobs:write
delete_job_outputs	按请求删除结果	jobs:write

配置和故障排除

环境变量	值
VIDEO_WORKER_API_KEY_FILE	私有纯文本密钥文件的绝对路径
VIDEO_WORKER_UPLOAD_ROOT	已存在的、经授权的媒体文件夹的绝对路径
VIDEO_WORKER_DOWNLOAD_ROOT	已存在的目标文件夹的绝对路径
VIDEO_WORKER_API_URL	可选；默认值为 https://videoworker.dev

VIDEO_WORKER_API_KEY 可在私有进程环境中使用，且优先级高于文件。切勿将其放入共享配置或命令行中。 自定义来源必须使用 HTTPS，但开发时显式指定的回环 HTTP 除外。

• ENOENT / 找不到服务： 使用上方显示的完整 Python 路径，而不是 Shell 别名。GUI 应用可能使用不同的 PATH。
• 配置错误： 在终端中设置相同的变量，然后运行 python -m videoworker_mcp --check。该命令仅验证本地设置，不会调用 API，也不会验证凭据或使用额度。查看帮助/版本无需密钥。
• 未授权 / 禁止访问： 在控制面板中检查密钥、权限范围和账户。切勿在支持消息中发送凭据。
• 文件被拒绝： 传入简单文件名，而不是路径或 URL。本地扩展名：mp4、mp3、wav、webm、gif、png、jpg、jpeg、mkv、mov、ogg、flac。链接文件夹以及符号链接/目录联接会被拒绝。
• 传输缓慢： 每次网络操作的上传/下载最长可能需要 15 分钟。在支持的情况下，请配置合适的工具调用超时。关闭工具调用不会取消已接受的处理任务。

数据和重试

服务会强制执行账户所有权、使用额度、文件限制和过期时间。 本地进程以你的操作系统用户身份运行；文件夹限制是应用层防护措施，并非操作系统沙箱。未捆绑或需要本地 FFmpeg。

下载不会覆盖文件，也不会跟随 Agent 提供的输出 URL。声明的输出大小上限为 1 GiB；没有大小信息的旧版元数据采用 50 MiB 的备用上限。传输采用流式处理，不会将完整视频加载到内存中。

重试任务时，请保留同一个 UUID request_id 和完全相同的参数（有效期 48 小时）。 不确定的响应仍可能表示操作已成功。上传操作不可幂等。轮询间隔不得短于 1 秒，并且要在过期前下载。只有收到服务器确认后，取消/删除才算完成。无需计费/管理权限。

开发

python -m pip install '.[dev]'
python -m pytest -q
python -m ruff check .
python -m ruff format --check .

测试使用小型受控 HTTP 测试夹具和实际的 MCP SDK 发现机制。请参阅发布检查、依赖项许可证和安全问题报告。

许可证和支持

连接器采用 MIT 许可证；托管处理服务和私有后端另行提供。可通过 GitHub 问题或 [email protected] 联系我们。

配置参考：Codex、 Claude Desktop、 Cursor。