FFmpeg Python MCP Server
Provides tools for video and audio processing using FFmpeg, including format conversion, cutting, merging, hardware acceleration (Intel QSV, NVIDIA NVENC), stream processing, and GIF generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FFmpeg Python MCP Server convert video.mp4 to audio.mp3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FFmpeg Python MCP 服务器
📋 项目简介
这是一个基于 Model Context Protocol (MCP) 的 FFmpeg 视频音频处理服务器。该项目为 AI 助手提供了强大的视频和音频处理能力,包括格式转换、切割合并、特效添加等功能,支持硬件加速处理。
🌟 主要特性
🎬 完整的视频音频处理功能 - 转换、切割、合并、压缩等
⚡ 硬件加速支持 - Intel QSV、NVIDIA NVENC 等
🔄 异步并发处理 - 支持多任务并行执行
🌐 流媒体支持 - M3U8 合并、直播流处理
🎨 视频特效 - 水印、GIF转换、变速等
🤖 AI友好接口 - 标准 MCP 协议,易于集成
Related MCP server: FFmpeg MCP
🚀 快速开始
前置要求
Python 3.12+
FFmpeg - 请先安装 FFmpeg:
# macOS brew install ffmpeg # Ubuntu/Debian sudo apt update && sudo apt install ffmpeg # Windows # 从 https://ffmpeg.org/download.html 下载uv 包管理器:
curl -LsSf https://astral.sh/uv/install.sh | sh
安装和运行
克隆项目
git clone https://github.com/mabh111111/ffmpeg_python_mcp.git cd ffmpeg_python_mcp安装依赖
uv sync运行 MCP 服务器
# 开发模式(推荐用于测试) uv run mcp dev main.py # 或直接运行 uv run python main.py
🔧 MCP 配置和使用
什么是 MCP?
Model Context Protocol (MCP) 是一个标准化协议,允许 AI 助手(如 Claude、ChatGPT 等)安全地访问外部工具和资源。
在 AI 客户端中配置
配置 Claude Desktop
打开 Claude Desktop 配置文件:
# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json添加 MCP 服务器配置:
{ "mcpServers": { "ffmpeg-processor": { "command": "uv", "args": ["run", "python", "/path/to/ffmpeg_python_mcp/main.py"], "cwd": "/path/to/ffmpeg_python_mcp" } } }重启 Claude Desktop
配置其他 MCP 客户端
对于支持 MCP 的其他客户端,使用以下连接信息:
命令:
uv run python main.py工作目录: 项目根目录
协议: stdio
验证连接
运行服务器后,你应该能在 AI 助手中看到以下可用工具:
视频音频提取和转换工具
切割和合并功能
硬件加速处理
视频特效和压缩
🛠️ 主要功能
📤 音频提取
# 从视频提取音频
extract_audio_from_video(video_path, output_path?, audio_format?, audio_quality?)
# 提取音频片段
extract_audio_segment(video_path, start_time, duration, output_path?, audio_format?)🔄 格式转换
# 视频格式转换
convert_video_format(input_path, output_path?, output_format?, video_codec?, audio_codec?, quality?)
# 音频格式转换
convert_audio_format(input_path, output_path?, output_format?, audio_codec?, bitrate?)✂️ 切割合并
# 视频切割
cut_video_segment(input_path, start_time, end_time?|duration?, output_path?)
# 视频合并
merge_videos(video_paths, output_path?, merge_method?)🎨 视频特效
# 转换为GIF
video_to_gif(input_path, output_path?, start_time?, duration?, width?, fps?, quality?)
# 添加水印
add_watermark(input_path, watermark_path, output_path?, position?, opacity?, margin?)
# 调整分辨率
resize_video(input_path, width, height, output_path?, keep_aspect_ratio?)🚀 硬件加速
# 检查硬件加速支持
check_hardware_acceleration()
# QSV硬件加速转换
convert_video_with_qsv(input_path, output_path?, output_format?, qsv_encoder?, quality?)🌐 流媒体处理
# M3U8合并
merge_m3u8_to_mp4(m3u8_url, output_path, headers?)⚡ 性能特性
异步并发处理
所有处理函数支持异步执行
AI 可同时调用多个工具进行并行处理
批量处理性能提升 3-5 倍
硬件加速
Intel QSV: 处理速度提升 3-10 倍
NVIDIA NVENC: GPU 硬件编码
自动检测: 智能选择最佳加速方案
📁 项目结构
ffmpeg_python_mcp/
├── main.py # MCP 服务器入口
├── src/ # 源代码模块
│ ├── tools/
│ │ └── math_tools.py # 数学工具(示例)
│ ├── resources/
│ │ └── greeting.py # 问候资源(示例)
│ └── config/
│ └── server_config.py # 配置管理
├── pyproject.toml # 项目配置
├── uv.lock # 依赖锁定
└── README.md # 项目文档🔧 开发指南
添加新工具
在相应模块中定义工具函数
使用
@server.tool装饰器注册添加完整的参数类型和文档字符串
@server.tool()
async def my_new_tool(input_path: str, option: str = "default") -> str:
"""
工具描述
Args:
input_path: 输入文件路径
option: 可选参数
Returns:
处理结果
"""
# 实现逻辑
return result运行测试
# 检查代码格式
uv run ruff check
# 运行开发模式
uv run mcp dev main.py🤝 贡献
欢迎提交 Issue 和 Pull Request!
Fork 本仓库
创建特性分支 (
git checkout -b feature/AmazingFeature)提交更改 (
git commit -m 'Add some AmazingFeature')推送到分支 (
git push origin feature/AmazingFeature)开启 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情
🆘 支持
GitHub Issues: 提交问题
🔗 相关链接
⭐ 如果这个项目对你有帮助,请给个 Star!
Available Tools
19 toolsadd_watermarkB
为视频添加水印
Args:
input_path: 输入视频文件路径
watermark_path: 水印图片路径
output_path: 输出视频文件路径(可选)
position: 水印位置(top-left, top-right, bottom-left, bottom-right, center)
opacity: 水印透明度(0.0-1.0)
margin: 水印边距像素
Returns:
添加结果信息
Inputs: input_path (required), watermark_path (required), output_path, position, +2 more.
change_video_speedA
改变视频播放速度
Args:
input_path: 输入视频文件路径
speed: 播放速度倍数(0.5=半速,1.0=原速,2.0=两倍速)
output_path: 输出视频文件路径(可选)
keep_audio_pitch: 是否保持音频音调不变
Returns:
速度调整结果信息
Inputs: input_path (required), speed (required), output_path, keep_audio_pitch.
check_hardware_accelerationB
检查系统支持的硬件加速选项
Returns:
硬件加速支持情况报告
Inputs: no named parameters.
compress_videoB
压缩视频文件
Args:
input_path: 输入视频文件路径
output_path: 输出视频文件路径(可选)
quality: 压缩质量(high, medium, low)
target_size_mb: 目标文件大小(MB,可选)
use_hardware_acceleration: 是否使用硬件加速
hwaccel_type: 硬件加速类型(qsv, nvenc, vaapi等)
Returns:
压缩结果信息
Inputs: input_path (required), output_path, quality, target_size_mb, +2 more.
compress_video_with_qsvB
使用Intel QSV硬件加速压缩视频
Args:
input_path: 输入视频文件路径
output_path: 输出视频文件路径(可选)
quality: 压缩质量(high, medium, low)
qsv_encoder: QSV编码器(h264_qsv, hevc_qsv等)
target_bitrate: 目标比特率(如"2M", "1000k")
Returns:
压缩结果信息
Inputs: input_path (required), output_path, quality, qsv_encoder, +1 more.
convert_audio_formatB
转换音频格式
Args:
input_path: 输入音频文件路径
output_path: 输出音频文件路径(可选)
output_format: 输出格式(mp3, wav, aac, flac, ogg等)
audio_codec: 音频编码器(libmp3lame, aac, flac等)
bitrate: 音频码率(128k, 192k, 320k等)
Returns:
转换结果信息
Inputs: input_path (required), output_path, output_format, audio_codec, +1 more.
convert_video_formatB
转换视频格式
Args:
input_path: 输入视频文件路径
output_path: 输出视频文件路径(可选)
output_format: 输出格式(mp4, avi, mov, mkv, flv等)
video_codec: 视频编码器(libx264, libx265, libvpx, h264_qsv, hevc_qsv等)
audio_codec: 音频编码器(aac, mp3, ac3等)
quality: 质量设置(high, medium, low)
use_hardware_acceleration: 是否使用硬件加速
hwaccel_type: 硬件加速类型(qsv, nvenc, vaapi等)
Returns:
转换结果信息
Inputs: input_path (required), output_path, output_format, video_codec, +4 more.
convert_video_with_qsvA
使用Intel QSV硬件加速转换视频
Args:
input_path: 输入视频文件路径
output_path: 输出视频文件路径(可选)
output_format: 输出格式(mp4, mkv, avi等)
qsv_encoder: QSV编码器(h264_qsv, hevc_qsv, av1_qsv等)
quality: 质量设置(high, medium, low)
qsv_preset: QSV预设(veryfast, faster, fast, medium, slow, slower, veryslow)
Returns:
转换结果信息
Inputs: input_path (required), output_path, output_format, qsv_encoder, +2 more.
cut_audio_segmentB
切割音频片段
Args:
input_path: 输入音频文件路径
start_time: 开始时间(格式:HH:MM:SS)
end_time: 结束时间(格式:HH:MM:SS,与duration二选一)
duration: 持续时间(格式:HH:MM:SS,与end_time二选一)
output_path: 输出音频文件路径(可选)
Returns:
切割结果信息
Inputs: input_path (required), start_time (required), end_time, duration, +1 more.
cut_video_segmentC
切割视频片段
Args:
input_path: 输入视频文件路径
start_time: 开始时间(格式:HH:MM:SS)
end_time: 结束时间(格式:HH:MM:SS,与duration二选一)
duration: 持续时间(格式:HH:MM:SS,与end_time二选一)
output_path: 输出视频文件路径(可选)
use_hardware_acceleration: 是否使用硬件加速(需要重新编码)
hwaccel_type: 硬件加速类型(qsv, nvenc, vaapi等)
precise_cut: 是否精确切割(重新编码,速度较慢但更精确)
Returns:
切割结果信息
Inputs: input_path (required), start_time (required), end_time, duration, +4 more.
extract_audio_from_videoA
从视频文件中提取音频
Args:
video_path: 输入视频文件路径
output_path: 输出音频文件路径(可选,默认与视频同目录)
audio_format: 音频格式(mp3, wav, aac, flac等)
audio_quality: 音频质量(如192k, 320k等)
Returns:
提取结果信息
Inputs: video_path (required), output_path, audio_format, audio_quality.
extract_audio_segmentC
从视频中提取指定时间段的音频
Args:
video_path: 输入视频文件路径
start_time: 开始时间(格式:HH:MM:SS)
duration: 持续时间(格式:HH:MM:SS)
output_path: 输出音频文件路径(可选)
audio_format: 音频格式
Returns:
提取结果信息
Inputs: video_path (required), start_time (required), duration (required), output_path, +1 more.
extract_framesB
从视频中提取帧图片
Args:
input_path: 输入视频文件路径
output_dir: 输出图片目录(可选)
fps: 提取帧率(如1表示每秒1帧,0.5表示2秒1帧)
start_time: 开始时间(格式:HH:MM:SS)
duration: 持续时间(格式:HH:MM:SS)
image_format: 图片格式(jpg, png, bmp)
Returns:
提取结果信息
Inputs: input_path (required), output_dir, fps, start_time, +2 more.
get_video_infoA
获取视频文件信息
Args:
video_path: 视频文件路径
Returns:
视频文件详细信息
Inputs: video_path (required).
merge_audiosB
合并多个音频文件
Args:
audio_paths: 音频文件路径列表,用逗号分隔
output_path: 输出音频文件路径(可选)
merge_method: 合并方式(concat:拼接,mix:混音)
Returns:
合并结果信息
Inputs: audio_paths (required), output_path, merge_method.
merge_m3u8_to_mp4B
合并M3U8流为MP4文件
Args:
m3u8_url: M3U8播放列表URL
output_path: 输出MP4文件路径
headers: 可选的HTTP头部信息(格式:key1:value1,key2:value2)
Returns:
合并结果信息
Inputs: m3u8_url (required), output_path (required), headers.
merge_videosB
合并多个视频文件
Args:
video_paths: 视频文件路径列表,用逗号分隔
output_path: 输出视频文件路径(可选)
merge_method: 合并方式(concat:简单拼接,filter:滤镜合并)
Returns:
合并结果信息
Inputs: video_paths (required), output_path, merge_method.
resize_videoC
调整视频分辨率
Args:
input_path: 输入视频文件路径
width: 目标宽度
height: 目标高度
output_path: 输出视频文件路径(可选)
keep_aspect_ratio: 是否保持宽高比
Returns:
调整结果信息
Inputs: input_path (required), width (required), height (required), output_path, +1 more.
video_to_gifB
视频转GIF动图
Args:
input_path: 输入视频文件路径
output_path: 输出GIF文件路径(可选)
start_time: 开始时间(格式:HH:MM:SS,可选)
duration: 持续时间(格式:HH:MM:SS,可选)
width: GIF宽度像素(高度自动按比例缩放)
fps: 帧率(建议5-15)
quality: 质量设置(high, medium, low)
Returns:
转换结果信息
Inputs: input_path (required), output_path, start_time, duration, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have distinct purposes, but pairs like compress_video/compress_video_with_qsv and convert_video_format/convert_video_with_qsv have similar functions differentiated only by hardware acceleration, which could cause agent confusion. Descriptions help clarify, but some ambiguity remains.
All tool names follow a consistent verb_noun pattern in snake_case. Variations like compress_video_with_qsv and video_to_gif are still predictable and within the convention, making the naming highly uniform.
With 19 tools, the server covers a broad range of video and audio operations without being bloated. Each tool addresses a specific need, and the count is well-suited for a multimedia processing server.
The tool set covers core media operations (convert, compress, cut, merge, extract, etc.) and includes specialized hardware acceleration support. Minor gaps exist, such as lack of volume adjustment or subtitle handling, but overall it's fairly comprehensive for typical use cases.
Related MCP Connectors
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Audio and video tools for your AI assistant: remove noise, enhance voices, transcribe, and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides powerful video and audio editing capabilities through FFmpeg, enabling AI assistants to perform professional-grade operations including format conversion, trimming, overlays, transitions, and advanced audio processing.2790MIT
- AlicenseAqualityDmaintenanceEnables video and audio processing through FFmpeg, supporting format conversion, compression, trimming, audio extraction, frame extraction, video merging, and subtitle burning through natural language commands.8170 PyPI28MIT
- AlicenseBqualityBmaintenanceProvides video and audio manipulation tools powered by FFmpeg, enabling AI assistants to perform media operations such as cutting, converting, and removing silence.6343 npm2MIT
- AlicenseAqualityDmaintenanceEnables local media processing (video/audio) using FFmpeg and FFprobe, allowing frame extraction, audio conversion, and metadata retrieval through natural language.5MIT