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：

開始使用

將以下配置添加到你的 MCP 客戶端：

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

MCP 客戶端配置

手動安裝

pip install ffmpeg-mcp-lite

或者使用 uv 進行安裝：

uv pip install ffmpeg-mcp-lite

🛠️ 可用工具

所有工具都以 ffmpeg_ 為前綴，以避免與其他 MCP 服務器發生命名衝突。

📊 媒體信息

🔄 轉換與壓縮

✂️ 編輯

🎵 音頻與幀提取

📝 字幕處理

💻 使用示例

獲取媒體信息

"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"

🔧 配置說明

環境變量

自定義配置

{
  "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 平臺

⬆ 返回頂部