FFmpeg MCP Tool

一个基于FFmpeg的MCP（Model Context Protocol）工具，用于处理图片和视频的转码、压缩等操作。

功能特性

图片处理

• 图片压缩（单个文件或批量处理）
• 图片格式转换（JPG、PNG、BMP、GIF、TIFF、WebP等）
• 图片尺寸调整
• 获取图片信息

视频处理

• 视频压缩（支持H.264编码）
• 视频格式转换（MP4、AVI、MKV、MOV等）
• 视频尺寸调整
• 获取视频信息

批量处理

• 支持批量压缩指定文件夹中的所有图片
• 支持批量压缩指定文件夹中的所有视频
• 自动识别常见的图片和视频格式

系统要求

1. Python 3.8+
2. FFmpeg（必须安装并可在命令行中使用）

安装步骤

1. 安装FFmpeg

Windows

• 下载FFmpeg：https://ffmpeg.org/download.html#build-windows
• 解压到某个目录（如 C:\ffmpeg）
• 将 C:\ffmpeg\bin 添加到系统PATH环境变量
• 打开命令提示符，运行 ffmpeg -version 验证安装

macOS

brew install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

2. 安装Python依赖

pip install -r requirements.txt

使用方法

1. 启动MCP服务器

python start_server.py

2. 配置MCP客户端

将 config.json 中的配置添加到你的MCP客户端配置中：

{
  "mcpServers": {
    "ffmpeg": {
      "command": "python",
      "args": ["path/to/ffmpeg_mcp.py"],
      "env": null
    }
  }
}

3. 可用工具

图片处理工具

compress_image

压缩单个图片文件

{
  "input_path": "D:/input/image.jpg",
  "output_path": "D:/output/compressed.jpg", 
  "quality": 85
}

batch_compress_images

批量压缩指定文件夹中的所有图片

{
  "input_dir": "D:/1",
  "output_dir": "D:/output",
  "quality": 85
}

convert_image_format

转换图片格式

{
  "input_path": "D:/input/image.png",
  "output_path": "D:/output/image.jpg"
}

resize_image

调整图片尺寸

{
  "input_path": "D:/input/image.jpg",
  "output_path": "D:/output/resized.jpg",
  "width": 800,
  "height": 600
}

视频处理工具

compress_video

压缩单个视频文件

{
  "input_path": "D:/input/video.mp4",
  "output_path": "D:/output/compressed.mp4",
  "crf": 23,
  "preset": "medium"
}

batch_compress_videos

批量压缩指定文件夹中的所有视频

{
  "input_dir": "D:/videos", 
  "output_dir": "D:/output",
  "crf": 23,
  "preset": "medium"
}

convert_video_format

转换视频格式

{
  "input_path": "D:/input/video.avi",
  "output_path": "D:/output/video.mp4"
}

resize_video

调整视频尺寸

{
  "input_path": "D:/input/video.mp4",
  "output_path": "D:/output/resized.mp4",
  "width": 1280,
  "height": 720
}

信息工具

get_media_info

获取媒体文件详细信息

{
  "file_path": "D:/media/file.mp4"
}

check_ffmpeg_status

检查FFmpeg是否安装并可用

{}

参数说明

图片压缩质量 (quality)

• 范围：1-100
• 数值越高，质量越好，文件越大
• 推荐值：80-90

视频压缩质量 (crf)

• 范围：18-28
• 数值越小，质量越高，文件越大
• 推荐值：
  • 高质量：18-20
  • 平衡：21-24
  • 小文件：25-28

视频压缩速度预设 (preset)

• ultrafast：最快速度，文件最大
• superfast, veryfast, faster, fast：速度递减，质量递增
• medium：平衡选择（默认）
• slow, slower, veryslow：速度最慢，质量最好

支持的文件格式

图片格式

• 输入：JPG, JPEG, PNG, BMP, GIF, TIFF, WebP
• 输出：根据输出文件扩展名自动判断

视频格式

• 输入：MP4, AVI, MKV, MOV, WMV, FLV, WebM, M4V
• 输出：根据输出文件扩展名自动判断

使用示例

批量压缩图片

假设你有一个文件夹 D:/1 包含很多JPG图片，想要压缩后保存到 D:/output：

# 使用MCP客户端调用
tool_call = {
    "name": "batch_compress_images",
    "arguments": {
        "input_dir": "D:/1",
        "output_dir": "D:/output", 
        "quality": 80
    }
}

视频格式转换

将AVI格式转换为MP4：

tool_call = {
    "name": "convert_video_format",
    "arguments": {
        "input_path": "D:/video.avi",
        "output_path": "D:/output/video.mp4"
    }
}

实际应用案例

网站图片批量优化

场景：网站有大量高分辨率图片需要优化以提高加载速度

操作：

用户：我需要优化网站的所有图片，它们在 D:/website/images 目录，
      请压缩到 D:/website/optimized，质量保持在 80-85 之间

AI助手自动执行：

1. 调用 batch_compress_images 工具
2. 处理目录中的所有图片
3. 生成压缩报告，显示节省的存储空间

结果：假设处理了 500 张图片，平均压缩率 60%，节省了约 2GB 存储空间。

视频素材格式转换

场景：将不同格式的视频素材统一转换为 MP4 格式

操作：

用户：把 D:/videos/raw 目录下的所有视频转换为 MP4 格式，
      保存到 D:/videos/mp4，使用中等压缩质量

AI助手处理流程：

1. 识别目录中的所有视频文件（AVI、MKV、MOV等）
2. 逐个转换为 MP4 格式
3. 应用 H.264 编码和 AAC 音频编码
4. 报告转换结果

社交媒体图片批量调整

场景：为不同社交平台准备合适尺寸的图片

操作：

用户：将 D:/photos/original 中的照片调整为 1080x1080 正方形，
      适合 Instagram 发布，保存到 D:/photos/instagram

AI助手会：

1. 调用 resize_image 工具
2. 批量处理所有图片
3. 调整为指定尺寸
4. 保持合适的压缩质量

错误处理

工具会自动处理常见错误：

• 输入文件不存在
• 输出目录不存在（会自动创建）
• FFmpeg命令执行失败
• 不支持的文件格式

注意事项

1. 确保有足够的磁盘空间用于输出文件
2. 大文件处理可能需要较长时间
3. 批量处理时会跳过无法处理的文件并在结果中报告
4. 输出路径中的目录会被自动创建

故障排除

FFmpeg未找到

错误：FFmpeg 未安装或不可用

解决方案：

1. 确认FFmpeg已正确安装
2. 确认FFmpeg已添加到系统PATH
3. 在命令行运行 ffmpeg -version 验证

文件权限错误

确保Python有读取输入文件和写入输出目录的权限。

内存不足

对于大文件或大量文件，可能需要：

1. 增加系统内存
2. 分批处理文件
3. 调整FFmpeg参数

开发和扩展

项目结构：

ffmpeg-mcp/
├── ffmpeg_mcp.py      # 主要的MCP服务器代码
├── requirements.txt   # Python依赖
├── config.json       # MCP配置文件
├── start_server.py   # 服务器启动脚本
├── test_example.py   # 使用示例
└── README.md        # 说明文档

如需添加新功能，可以：

1. 在 FFmpegProcessor 类中添加新的处理方法
2. 在 handle_list_tools() 中注册新工具
3. 在 handle_call_tool() 中处理新工具的调用

许可证

MIT License - 可自由使用和修改。