FFmpeg MCP Server

ffmpeg-mcp-server

一个模型上下文协议（MCP）服务，可让 AI 工具在本地使用 FFmpeg 和 FFprobe 处理视频和音频。

支持 Apple Silicon 硬件编码，并可将图像预览直接返回给具备视觉能力的模型。

---

为什么要开发此项目

AI Agent 处理媒体时，经常会虚构无效标志、语法错误或不兼容的像素格式。

此服务提供 13 个基于 Zod 架构的类型化工具。AI 传入参数（例如 { inputPath: "video.mov", preset: "web_mp4" }），服务便会在本地运行有效的 FFmpeg 命令。

---

主要功能

• 硬件编码： 在 macOS 上使用 VideoToolbox 加速导出，同时降低 CPU 使用率。
• 图像响应： 返回 Base64 图像，让视觉模型检查缩略图和波形。
• 社交媒体格式： 将横屏视频转换为 9:16 竖屏视频，并以模糊背景补齐画面。
• 分屏： 将两段视频上下堆叠，用于 Reels 和 TikTok，并可选择添加字幕和混合音频。
• 静音移除： 检测并剪除语音录音中的停顿。

---

内置工具（共 13 个）

工具	描述	主要参数
media_probe	使用 ffprobe 检查媒体文件。以 JSON 格式返回元数据、流、编解码器、分辨率和时长。	inputPath
media_convert	转换视频和音频格式。包含适用于 Web MP4、WebM 和动态 GIF 的预设。	inputPath、outputPath、preset、crf、resolution、fps、hardwareAcceleration
trim_media	使用流复制或重新编码，从视频或音频文件中截取片段。	inputPath、outputPath、startTime、endTime、duration、accurateReencode
extract_audio	从视频中提取音轨。包含用于 Whisper 语音识别的 16kHz 单声道 WAV 预设。	inputPath、outputPath、format、bitrate
extract_thumbnail	在指定时间戳或视频中点截取静态图像。返回供视觉模型使用的 base64 图像数据。	inputPath、outputPath、timestamp、resolution、includeBase64
compress_video	压缩视频以满足目标大小（例如，将 GitHub PR 视频压至 10MB 以下，或将 Discord 视频压至 25MB 以下）。	inputPath、outputPath、targetSizeMB、preset、crf、maxWidth、hardwareAcceleration
reformat_aspect_ratio	将视频比例调整为 9:16 竖屏、1:1 正方形或 4:5 竖版，并添加模糊边框或进行中心裁剪。	inputPath、outputPath、targetRatio、mode、blurAmount、padColor
create_split_screen	将两个视频上下堆叠（9:16 Reels/TikTok）或并排排列，并混合音频和添加字幕。	firstVideoPath、secondVideoPath、outputPath、layout、audioSource、subtitlesPath
trim_silence	检测并移除录音中的静音间隔。报告时长以及节省的秒数。	inputPath、outputPath、mode、thresholdDb、minDurationSeconds
concat_media	使用流复制或重新编码，按顺序合并多个视频或音频文件。	inputPaths、outputPath、mode
generate_waveform	生成 PNG 波形图像。返回供视觉模型使用的 base64 图像数据。	inputPath、outputPath、width、height、color、scale、includeBase64
add_subtitles	将 SRT 或 VTT 字幕轨道嵌入视频文件，而无需重新编码视频。	videoPath、subtitlesPath、outputPath、language、title
change_speed	调整播放速度（例如，2 倍快进或 0.5 倍慢动作），并校正音调。	inputPath、outputPath、speed、muteAudio

---

要求

• Node.js >= 18.0.0
• 本地已安装 FFmpeg 和 FFprobe：
  • macOS： brew install ffmpeg
  • Linux（Ubuntu/Debian）： sudo apt update && sudo apt install ffmpeg
  • Windows： winget install Gyan.FFmpeg 或 choco install ffmpeg

---

安装

快速开始（Claude Desktop、Cursor、Antigravity）

使用 npx 直接运行（无需手动克隆或构建）：

{
  "mcpServers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@ash_j1997/ffmpeg-mcp-server"]
    }
  }
}

配置文件位置：

• Claude Desktop（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）： %APPDATA%\Claude\claude_desktop_config.json
• Antigravity IDE： ~/.gemini/config/mcp_config.json
• Cursor / Windsurf： 将其添加为 stdio 服务，命令设为 npx，参数设为 `["-y", "@ash_j1997/ffmpeg-mcp-server"]

---

本地开发

1. 安装依赖：

   npm install
   

2. 构建 TypeScript：

   npm run build
   

3. 运行测试：

   node test-tools.js
   

---

许可证

MIT © Ashutos1997