ffmpeg-mcp-lite

🚀 🎬 ffmpeg-mcp

ffmpeg-mcp 是一个强大的 MCP 服务器，可通过 FFmpeg 进行视频和音频处理。 它能将 FFmpeg 与 Claude、Dive 等支持 MCP 的 AI 系统集成，让你通过自然语言实现视频转换、压缩、裁剪、音频提取等操作。

主要特性 • 安装指南 • 可用工具 • 使用示例 • 配置说明

🚀 快速开始

ffmpeg-mcp 是一个借助 FFmpeg 实现强大音视频处理功能的 MCP 服务器。你可以通过自然语言指令，轻松完成视频和音频的各种处理任务。

✨ 主要特性

📊 媒体信息

• 获取全面的元数据，包括时长、分辨率、编解码器等。
• 支持以 JSON 格式输出详细的比特率和流信息。

🔄 格式转换

• 支持在多种格式间进行转换，如 MP4、MKV、WebM、MOV 等。
• 可自定义视频和音频编解码器，并进行分辨率缩放。

🗜️ 视频压缩

• 提供低、中、高三种质量预设。
• 可控制编码速度，优化 H.264 编码，同时显示文件大小缩减统计信息。

✂️ 视频裁剪

• 支持按精确的开始和结束时间进行裁剪。
• 可基于时长进行裁剪，采用流复制方式，无需重新编码，速度快。

🎵 音频提取

• 支持多种音频格式，如 MP3、AAC、WAV、FLAC、OGG、Opus。
• 可控制比特率，输出高质量音频。

🎞️ 高级功能

• 支持合并多个视频文件。
• 可按时间间隔或数量提取视频帧为图片，支持 JPG、PNG、BMP 输出。

📝 字幕处理

• 支持将 SRT/ASS/VTT 字幕嵌入视频。
• 提供多种字幕样式，可自定义字体大小，与 Whisper MCP 配合良好。

📦 安装指南

前提条件

在你的系统上安装 FFmpeg： | 平台 | 命令 | | ---- | ---- | | 🪟 Windows | winget install FFmpeg | | 🍎 macOS | brew install ffmpeg | | 🐧 Linux | sudo apt install ffmpeg |

开始使用

将以下配置添加到你的 MCP 客户端：

{
  "mcpServers": {
    "ffmpeg": {
      "command": "uvx",
      "args": ["ffmpeg-mcp-lite"]
    }
  }
}

MCP 客户端配置

手动安装

pip install ffmpeg-mcp-lite

或者使用 uv 进行安装：

uv pip install ffmpeg-mcp-lite

🛠️ 可用工具

所有工具都以 ffmpeg_ 为前缀，以避免与其他 MCP 服务器发生命名冲突。

📊 媒体信息

| 工具 | 描述 | | ---- | ---- | | ffmpeg_get_info | 获取全面的视频/音频元数据。
参数：file_path
返回：包含时长、分辨率、编解码器、比特率、流信息的 JSON |

🔄 转换与压缩

| 工具 | 描述 | | ---- | ---- | | ffmpeg_convert | 将视频/音频转换为不同格式。
参数：file_path, output_format, scale, video_codec, audio_codec
支持格式：mp4, mkv, webm, mov, mp3, wav 等 | | ffmpeg_compress | 压缩视频以减小文件大小。
参数：file_path, quality, scale, preset
质量选项：low, medium, high
预设选项：ultrafast 到 veryslow |

✂️ 编辑

| 工具 | 描述 | | ---- | ---- | | ffmpeg_trim | 裁剪视频以提取片段。
参数：file_path, start_time, end_time 或 duration
时间格式："00:01:30" 或秒数 | | ffmpeg_merge | 将多个视频拼接成一个。
参数：file_paths (列表), output_path
支持：相同编解码器的视频 |

🎵 音频与帧提取

| 工具 | 描述 | | ---- | ---- | | ffmpeg_extract_audio | 从视频中提取音频轨道。
参数：file_path, audio_format, bitrate
支持格式：mp3, aac, wav, flac, ogg, opus | | ffmpeg_extract_frames | 将视频帧提取为图片。
参数：file_path, interval 或 count, format
支持格式：jpg, png, bmp |

📝 字幕处理

| 工具 | 描述 | | ---- | ---- | | ffmpeg_add_subtitles | 将字幕嵌入视频（硬编码）。
参数：file_path, subtitle_path, style, font_size, output_path
支持格式：SRT, ASS, VTT
样式选项：outline, shadow, background, glow |

💻 使用示例

获取媒体信息

"Get info about /path/to/video.mp4"
"What's the resolution and duration of this video?"
"Show me the codec information for my video"

视频转换

"Convert video.mp4 to WebM format"
"Convert this video to MKV with h265 codec"
"Convert and scale to 1280x720"

视频压缩

"Compress video.mp4 with medium quality"
"Compress this video to reduce file size, use fast preset"
"Compress with high quality and scale to 1920:-1"

视频裁剪

"Trim video.mp4 from 00:01:00 to 00:02:30"
"Cut the first 30 seconds from this video"
"Extract a 1-minute clip starting at 5:00"

音频提取

"Extract audio from video.mp4 as MP3"
"Get the audio track in AAC format with 192k bitrate"
"Extract audio as FLAC for best quality"

帧提取

"Extract one frame every 5 seconds from video.mp4"
"Get 10 frames evenly distributed from this video"
"Extract frames as PNG images"

视频合并

"Merge video1.mp4 and video2.mp4 together"
"Concatenate these three videos into one"

添加字幕

"Add subtitles.srt to video.mp4"
"Burn in Chinese subtitles with shadow style"
"Add subtitles with font size 32 and glow effect"

🔧 配置说明

环境变量

| 变量 | 描述 | 默认值 | | ---- | ---- | ---- | | FFMPEG_PATH | FFmpeg 二进制文件的路径 | ffmpeg | | FFPROBE_PATH | ffprobe 二进制文件的路径 | ffprobe | | FFMPEG_OUTPUT_DIR | 默认输出目录 | ~/Downloads |

自定义配置

{
  "mcpServers": {
    "ffmpeg": {
      "command": "uvx",
      "args": ["ffmpeg-mcp-lite"],
      "env": {
        "FFMPEG_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

📚 详细文档

架构说明

构建工具

• FFmpeg - 视频/音频处理引擎
• FastMCP - MCP Python 框架
• asyncio - 异步子进程执行
• Python 3.10+ - 类型提示和现代特性

关键特性

• ✅ 异步处理：非阻塞的 FFmpeg 执行
• ✅ 类型安全：使用 mypy 验证的完整类型提示
• ✅ 充分测试：使用 pytest 进行 31 个测试用例的测试
• ✅ 跨平台支持：可在 Windows、macOS、Linux 上运行
• ✅ 模块化设计：每个工具一个文件

贡献说明

欢迎贡献代码！

1. Fork 仓库。
2. 创建特性分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开 Pull Request。

开发步骤

# 克隆并安装
git clone https://github.com/kevinwatt/ffmpeg-mcp-lite.git
cd ffmpeg-mcp-lite
uv sync

# 运行测试
uv run pytest

# 类型检查
uv run mypy src/

# 代码检查
uv run ruff check src/

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• FFmpeg - 强大的多媒体框架
• Anthropic - 提供模型上下文协议
• Dive - 支持 MCP 的 AI 平台

⬆ 返回顶部