AI导哈

音频处理服务器

一个安全的容器化MCP服务器，为AI助手提供FFmpeg音频处理功能，支持批量处理多种音频格式并保持输出格式一致。

  • by danialrami
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 danialrami/ffmpeg-mcp-server

使用说明

FFmpeg MCP音频处理服务器

一个安全的容器化MCP（模型上下文协议）服务器，为AI助手提供任何FFmpeg。使用一致的输出格式处理整个音频文件目录，同时通过Docker沙盒维护安全性。

特性

  • 通用音频格式支持：处理40多种音频格式，包括WAV、MP3、FLAC、OGG、M4A等
  • 标准化输出：所有文件转换为48kHz、32位WAV格式，保留通道计数
  • 批处理：通过进度跟踪和详细报告处理整个目录
  • 安全第一:
    • 所有FFmpeg命令都在沙盒Docker容器中运行
    • 处理过程中禁用网络访问
    • 全面的指挥净化
    • 文件大小限制（默认7GB）
  • 智能处理:
    • 自动音频元数据提取
    • 通道计数保存
    • 带时间戳的输出目录可防止覆盖
    • 超时保护（每个文件5分钟）
  • MCP集成：与支持模型上下文协议的AI助手无缝集成

它的用途

此工具专为音频专业人员、声音设计师和开发人员设计，他们需要：

  • 对大型音频库应用一致的处理
  • 在保持质量的同时转换音频格式
  • 在批处理操作中安全地应用FFmpeg过滤器和效果
  • 将音频处理集成到AI驱动的工作流程中
  • 确保可复制、标准化的输出格式

需求

系统要求

  • python：3.7或更高
  • 码头工人：已安装并正在运行
  • MCP框架: pip install mcp
  • 存储：足够的音频文件空间（每个文件最多支持7GB）

自动设置

服务器自动执行以下操作：

  • 检查启动时的所有依赖关系
  • 如果不存在，则提取FFmpeg Docker映像
  • 在处理之前验证系统准备就绪

安装

  1. 克隆或下载此存储库

  2. 安装Python依赖项:

    pip install mcp

  3. 确保Docker已安装并正在运行:

    docker --version
docker ps

  4. 运行服务器:

    python ffmpeg_server.py

用法

作为MCP服务器

服务器为AI助手提供了三个主要工具：

1. any_ffmpeg_command

使用自定义FFmpeg命令处理音频文件：

{
    "directory": "/path/to/audio/files",
    "command_template": ["-i", "{input}", "-af", "loudnorm", "{output}"],
    "file_extensions": ["wav", "mp3"],  # Optional: defaults to all audio formats
    "output_subdir": "processed",       # Optional: defaults to "output"
    "max_file_size_mb": 7000           # Optional: defaults to 7000 (7GB)
}

2. get_audio_processing_info

获取有关服务器功能的信息：

  • 支持的音频格式
  • 可用的FFmpeg标志
  • 命令模板示例
  • 当前Docker状态

3. check_system_dependencies

验证是否满足所有系统依赖关系：

  • Python版本
  • Docker可用性
  • FFmpeg图像状态
  • MCP框架

FFmpeg命令示例

服务器包括几个示例模板：

# Simple format conversion
["-i", "{input}", "{output}"]

# Audio normalization
["-i", "{input}", "-af", "loudnorm", "{output}"]

# Trim audio (10s to 30s)
["-i", "{input}", "-ss", "10", "-t", "20", "{output}"]

# Apply reverb effect
["-i", "{input}", "-af", "aecho=0.8:0.9:1000:0.3", "{output}"]

# Normalize and compress
["-i", "{input}", "-af", "loudnorm,acompressor=threshold=-20dB:ratio=4:attack=5:release=50", "{output}"]

输出结构

已处理的文件保存在带时间戳的目录中：

input_directory/
├── audio1.mp3
├── audio2.flac
├── processed_20250103_143052/
│   ├── audio1_processed.wav
│   └── audio2_processed.wav
└── processed_20250103_151230/
    └── audio1_processed.wav

安全功能

  • 沙盒执行：所有FFmpeg命令都在Docker容器中运行，没有网络访问权限
  • 命令消毒：基于白名单的FFmpeg标志和参数验证
  • 外壳注射保护：全面检查恶意字符
  • 资源限制：文件大小限制和处理超时
  • 用户隔离：容器以无特权用户身份运行

高级配置

自定义文件大小限制

调整 max_file_size_mb 参数（默认值：7000 MB）

处理超时

当前设置为每个文件5分钟（硬编码）

支持的FFmpeg标志

服务器支持全面的音频处理标志白名单，包括：

  • 音频编解码器和格式
  • 质量和比特率设置
  • 过滤器和效果
  • 元数据处理
  • 基于时间的操作

故障排除

常见问题

  1. “Docker不可用”

    • 确保Docker桌面正在运行
    • 检查Docker守护进程： docker ps

  2. “未找到FFmpeg Docker映像”

    • 服务器将自动提取图像
    • 手动拉动： docker pull jrottenberg/ffmpeg

  3. “缺少Python依赖项”

    • 安装MCP： pip install mcp

  4. 处理超时

    • 检查文件大小和复杂性
    • 如果需要，简化FFmpeg过滤器

调试模式

使用Python的verbose标志运行以获得详细输出：

python -v ffmpeg_mcp_server.py

贡献

欢迎投稿！请确保：

  • 代码遵循现有样式模式
  • 安全措施得到维护
  • 测试通过（如适用）
  • 文档已更新

致谢

  • 基于MCP（模型上下文协议）框架构建
  • 使用优秀 jrottenberg/ffmpeg Docker镜像
  • 专为与AI助手和音频处理工作流程集成而设计

支持

对于问题、疑问或贡献：

  • 在存储库上打开问题
  • 检查现有文档
  • 确保满足系统要求

备注：此工具仅处理音频文件。视频流被忽略，所有输出都标准化为48kHz、32位WAV格式，保留了原始通道计数。

内置于🩷 通过LUFS音频

相关 MCP