mcp-ffmpeg-tools

mcp-ffmpeg-tools

一个开源的 Python MCP（Model-Command Protocol）服务，旨在让大模型（LLM）能够执行 FFmpeg 命令、接收执行结果，并根据 FFmpeg 源代码验证命令。

前置条件

安装 mcp-ffmpeg-tools 前，需要先在系统上安装 FFmpeg：

Windows

1. 从 ffmpeg.org 下载 FFmpeg
2. 将压缩包解压到任意位置
3. 将 bin 目录添加到系统 PATH

macOS

brew install ffmpeg

Linux（Ubuntu/Debian）

sudo apt update
sudo apt install ffmpeg

Linux（Fedora）

sudo dnf install ffmpeg

功能

• 通过 MCP 接口执行 FFmpeg 命令
• 接收详细的执行结果和错误消息
• 访问 FFmpeg 源代码以更正命令
• 支持跨平台（Windows、macOS、Linux）
• 使用 uv 管理环境

安装

1. 克隆代码库：

git clone https://github.com/gamhoi/mcp-ffmpeg-tools.git
cd mcp-ffmpeg-tools

2. 使用 uv 安装：

uv venv
uv pip install -e .

安装过程将会：

1. 验证 FFmpeg 是否已安装且可通过系统 PATH 访问
2. 下载用于验证的对应 FFmpeg 源代码
3. 安装 Python 包及其依赖项

如果未找到 FFmpeg 或源代码下载失败，安装将失败。

用法

与 Claude Desktop 搭配使用

将以下配置添加到 Claude Desktop 设置中：

{
    "mcpServers": {
        "mcp-ffmpeg-tools": {
            "command": "uv",
            "args": [
                "--directory",
                "PATH_TO/mcp-ffmpeg-tools",
                "run",
                "ffmpeg-tools"
            ]
        }
    }
}

运行测试

uv run python3 client/test.py

提示词示例

基础提示词

Help me perform media conversion tasks using FFmpeg. You can:
- use tool:execute_ffmpeg to run FFmpeg commands
- use tool:execute_ffprobe to inspect results (e.g., resolution, bitrate)
- use tool:get_screenshot to inspect results (e.g., video layout, quality)
- use tool:ls_ffmpeg_source_code and tool:get_ffmpeg_source_code to validate commands using FFmpeg source code

提取视频和音频

Extract all media streams from the file 'YOU_FILE_PATH' and save outputs to 'YOU_OUTPUT_PATH'

叠加 2 个视频

Overlay file1 'YOU_FILE_PATH_1' and file2 'YOU_FILE_PATH_2', using file1 as the background. Scale file2 down to half its original resolution and position it at the top-right corner of file1. Save the output to 'YOUR_OUTPUT_PATH'.

使用 Docker 运行

你可以通过 Docker 以 HTTP 模式运行 MCP FFmpeg Tools。 这样可以通过 HTTP 端口公开 MCP API（/mcp），供客户端使用。

选项 1 — 从 Docker Hub 拉取

你可以直接从 Docker Hub 拉取并运行官方镜像：

docker pull gamhoi/mcp-ffmpeg-tools:latest

在端口 8000 上运行：

docker run -d -p 8000:8000 gamhoi/mcp-ffmpeg-tools:latest --port 8000

将以下配置添加到 Claude Desktop 设置中：

{
    "mcpServers": {
        "mcp-ffmpeg-tools-http": {
            "type": "streamableHttp",
            "url": "http://localhost:8000/mcp"
        }
    }
}

注意：默认 URL http://localhost:8000/mcp 假定 MCP 服务在本地运行。 如果你在远程或联网环境中运行，请将 localhost 替换为主机 IP 或域名。

选项 2 — 本地构建

如果你更愿意通过 Dockerfile 构建：

docker build -t mcp-ffmpeg-tools .

访问本地文件

默认情况下，容器内的 ffmpeg 无法访问 Docker 外部的本地文件。 若要让它处理本地视频，必须将主机目录挂载到容器中。

示例：

docker run -d -p 8000:8000 -v /local_media:/media gamhoi/mcp-ffmpeg-tools:latest --port 8000

在此示例中：

• 你可以将本地视频文件放在：/local_media/sample.mp4
• 在容器内，同一文件可通过以下路径访问：/media/sample.mp4

因此，当你要求大模型处理本地文件时，应这样操作：

Extract all media streams from the file /media/sample.mp4 and save outputs to /media/