FFmpeg MCP Server

io.github.Ashutos1997由 GitHub 帳號 Ashutos1997 發布v0.6.0更新於 Nov 5, 2026

FFmpeg & FFprobe media processing toolkit for video, audio, and social formats

已驗證STDIO僅桌面檔案與儲存媒體與設計

概覽

AI 產生的概覽

本機 MCP 伺服器，透過 FFmpeg 與 FFprobe 讓助理檢查、轉檔、剪輯、壓縮影音並加上字幕。

可以做什麼
  • 檢查媒體：用 ffprobe 讀取編碼、解析度、位元率與長度，並偵測場景切換與剪接點。
  • 轉檔與剪輯：依網頁 MP4、WebM、GIF 預設轉換格式，裁切片段、串接檔案、調整播放速度、合併或替換音軌。
  • 配合社群平台：改成 9:16、1:1 或 4:5 比例，製作分割畫面短影音，壓縮到指定檔案大小，加上浮水印。
  • 音訊處理：擷取音軌（含供語音辨識使用的 16kHz 單聲道 WAV 預設），依 EBU R128 標準統一音量，移除無聲片段。
  • 字幕：嵌入 SRT 或 VTT 字幕軌，或將字幕燒錄進畫面並自訂樣式。
  • 視覺預覽：產生縮圖、關鍵影格拼圖與波形 PNG，回傳檔案路徑並內嵌 base64 影像供視覺模型檢視。
適用情境
適合需要處理本機影音檔案的情況：為社群平台準備直式短片、把檔案壓到上傳大小限制內、擷取音訊做轉錄，或讓視覺模型檢視畫面。也適合希望由伺服器產生正確 FFmpeg 指令、而非手寫參數的剪輯與媒體前置作業。
執行需求
以本機 stdio 程序執行，通常透過 npx 啟動 npm 套件。需要 Node.js 18 以上版本，並在本機安裝 FFmpeg 與 FFprobe（Linux 上處理字幕還需 libass）。未宣告需要帳號、API 金鑰或環境變數。硬體編碼取決於本機 GPU 與驅動程式。
安裝前請注意
它會在本機對檔案執行 FFmpeg，可讀取助理被指定的任何路徑並寫出新檔案，執行前請確認輸出路徑。部分工具會在目標位置建立或覆寫檔案，compress_video 聲明不會修改原始檔。媒體內容（包括 base64 影格）會回傳到模型脈絡中。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 FFmpeg MCP Server，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

ffmpeg-mcp-server

English | 한국어

[CI] [Release] [License: MIT] [npm version] [npm downloads] [npm total downloads] [Glama] [FFmpeg MCP server]

A Model Context Protocol (MCP) server that gives AI tools access to FFmpeg and FFprobe to process video and audio locally.

Supports cross-platform GPU hardware encoding (Apple Silicon, NVIDIA NVENC, Intel QuickSync, AMD AMF), live progress updates via MCP progress tokens, instant cancellation via AbortSignal, and inlines image previews directly for multimodal vision models.

Why This Exists

When AI agents process media, they often hallucinate invalid flags, syntax errors, or incompatible pixel formats.

This server provides 19 typed tools using Zod schemas. The AI passes parameters (such as { inputPath: "video.mov", preset: "web_mp4" }), and the server runs the valid FFmpeg command locally with proper error handling, hardware acceleration, and progress notifications.

Key Features

  • Universal Hardware Acceleration: Automatically detects and leverages hardware encoders across macOS (VideoToolbox), Linux/Windows GPUs (NVIDIA NVENC, Intel QuickSync, AMD AMF, and VA-API) for 5x–20x faster exports with low CPU usage.
  • Real-time Progress Reporting: Emits live percentage updates via standard MCP progress tokens (notifications/progress), enabling progress bars in modern AI clients.
  • Instant Cancellation: Listens to client AbortSignal events to immediately terminate child FFmpeg processes when a generation is stopped.
  • Multimodal Vision Previews: Inlines base64 image data for thumbnails, audio waveforms, and multi-frame contact sheets so vision models (Claude 3.7, GPT-4o, Gemini) can "see" media content.
  • Social Formats & Automation: Reformats landscape video to 9:16 vertical video with blurred backgrounds, burns customizable hardcoded subtitles, and stacks top/bottom split-screen reels for TikTok and Instagram Reels.
  • Audio Engineering: Normalizes loudness to broadcast/streaming standards (EBU R128 / -16 LUFS), cleans vocal audio with 80Hz rumble removal, and trims dead air while preserving lip-sync.
  • Scene Intelligence & Multiplexing: Detects visual scene changes and cut points for smart editing workflows, and combines or replaces video/audio tracks with zero-loss stream copy.

Included Tools (19 Total)

ToolDescriptionKey Parameters
media_probeInspects media files with ffprobe. Returns metadata, streams, codecs, resolution, and duration as JSON.inputPath
media_convertConverts video and audio formats. Includes presets for web MP4, WebM, and animated GIF with GPU acceleration.inputPath, outputPath, preset, crf, resolution, fps, hardwareAcceleration
trim_mediaCuts a segment from a video or audio file using stream copy or re-encoding.inputPath, outputPath, startTime, endTime, duration, accurateReencode
extract_audioRips audio tracks from video. Includes a 16kHz mono WAV preset for Whisper speech recognition.inputPath, outputPath, format, bitrate
extract_thumbnailCaptures a still image at a timestamp or midpoint. Returns base64 image data for vision models.inputPath, outputPath, timestamp, resolution, includeBase64
compress_videoCompresses video to fit target sizes (such as GitHub PRs under 10MB or Discord under 25MB).inputPath, outputPath, targetSizeMB, preset, crf, maxWidth, hardwareAcceleration
reformat_aspect_ratioChanges video ratio to 9:16 vertical, 1:1 square, or 4:5 portrait with blurred borders or center crop.inputPath, outputPath, targetRatio, mode, blurAmount, padColor, hardwareAcceleration
create_split_screenStacks two videos top-and-bottom (9:16 Reels/TikTok) or side-by-side with audio mixing and subtitles.firstVideoPath, secondVideoPath, outputPath, layout, audioSource, subtitlesPath
trim_silenceDetects and removes silent pauses from recordings while preserving video & audio lip-sync.inputPath, outputPath, mode, thresholdDb, minDurationSeconds
concat_mediaJoins multiple video or audio files in order using stream copy or re-encoding.inputPaths, outputPath, mode
generate_waveformGenerates a PNG waveform image. Returns base64 image data for vision models.inputPath, outputPath, width, height, color, scale, includeBase64
add_subtitlesEmbeds SRT or VTT subtitle tracks into MP4/MKV video files without re-encoding video.videoPath, subtitlesPath, outputPath, language, title
burn_subtitlesHardcodes subtitles directly onto video frames with customizable font size, colors, and margins.videoPath, subtitlesPath, outputPath, fontSize, fontColor, outlineColor, marginV
extract_keyframesExtracts multiple representative frames across the video and generates a contact sheet grid for vision AI.inputPath, outputPath, count, layout, includeBase64
normalize_audioNormalizes audio loudness using EBU R128 (default -16 LUFS) with optional speech clarity high-pass filter.inputPath, outputPath, targetLufs, targetPeakDb, voiceClarity
add_overlayPlaces a watermark image or logo PNG over video with customizable corner position, scale, and opacity.videoPath, overlayPath, outputPath, position, padding, scaleWidth, opacity
change_speedAdjusts playback speed (such as 2x fast forward or 0.5x slow motion) with pitch correction.inputPath, outputPath, speed, muteAudio
mux_media (New)Combines or replaces video and audio streams with optional audio offset delay and zero-loss stream copy.videoPath, audioPath, outputPath, mode, audioOffsetSeconds, streamCopyVideo, shortest
detect_scenes (New)Detects video cut points and scene transitions with adjustable sensitivity. Returns timestamps, scene durations, and an optional contact sheet.inputPath, threshold, minDurationSeconds, outputPath, includeBase64

MCP Resources & Prompts

Resources

  • media://capabilities: Inspects local FFmpeg installation, active version, detected hardware accelerators (VideoToolbox, NVENC, QSV, AMF, VAAPI), and supported video encoders.
  • media://presets: Standard reference table of social aspect ratios, platform upload file size limits, and broadcast audio loudness targets.

Prompts

  • social_clip_generator: Interactive workflow that turns raw landscape video into vertical shorts with blurred background padding, trimmed silence, and hardcoded captions.
  • whisper_audio_prep: Standard pipeline for extracting 16kHz mono WAV audio and normalizing loudness for speech-to-text models.

Requirements

  • Node.js >= 18.0.0
  • FFmpeg & FFprobe installed locally:
    • macOS: brew install ffmpeg
    • Linux (Ubuntu/Debian): sudo apt update && sudo apt install ffmpeg libass-dev
    • Windows: winget install Gyan.FFmpeg or choco install ffmpeg

Installation

Quick Start (Claude Desktop, Cursor, Antigravity)

Run directly with npx (no manual cloning or building required):

json
{  "mcpServers": {    "ffmpeg": {      "command": "npx",      "args": ["-y", "@ash_j1997/ffmpeg-mcp-server"]    }  }}
Configuration File Locations:
  • 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: Add as a stdio server with command npx and args ["-y", "@ash_j1997/ffmpeg-mcp-server"]

Local Development & Testing

  1. Install dependencies:

    bash
    npm install

  2. Run build and automated test suite:

    bash
    npm test

Acknowledgements & Community

Special thanks to @rajarshidattapy for suggesting the stream multiplexing (mux_media) and scene transition detection (detect_scenes) capabilities to expand the server beyond format conversion.

License

MIT © Ashutos1997

來源：README.md，提交 c18838b

工具

19

media_probe

Inspect audio and video files with ffprobe. Returns container metadata, stream details, codecs, resolution, bitrate, and duration as JSON.

輸入參數inputPath必填

media_convert

Convert video and audio files between formats. Includes presets for web MP4 (H.264/AAC), WebM (VP9/Opus), and animated GIF. Supports hardware acceleration on Apple Silicon, NVIDIA, Intel, and AMD.

輸入參數crffpspresetinputPath必填outputPath必填resolutionhardwareAcceleration

trim_media

Cut a segment from a video or audio file. Uses stream copy without re-encoding by default, or re-encodes when accurate cuts are needed.

輸入參數endTimedurationinputPath必填startTime必填outputPath必填accurateReencode

extract_audio

Extract an audio track from a video file into a standalone audio file. Supports the 'whisper_wav' preset (16kHz mono WAV) for speech recognition models, plus MP3, AAC, FLAC, and stream copy.

輸入參數formatbitrateinputPath必填outputPath必填

extract_thumbnail

Capture a single still image from a video. Returns the saved image path and inlined base64 image data so vision models can inspect the frame.

輸入參數inputPath必填timestampoutputPath必填resolutionincludeBase64

compress_video

Compress video files to fit upload limits (such as GitHub PRs under 10MB or Discord under 25MB) using target file sizes or CRF quality levels. Does not modify the original file.

輸入參數crfpresetmaxWidthinputPath必填outputPath必填targetSizeMBhardwareAcceleration

concat_media

Join multiple video or audio files in order into a single file. Uses stream copy for matching files or re-encodes when formats differ.

輸入參數modeinputPaths必填outputPath必填

generate_waveform

Generate a PNG waveform image from an audio or video file. Returns the file path and inlined base64 image data.

輸入參數colorscalewidthheightinputPath必填outputPath必填includeBase64

add_subtitles

Embed an SRT or VTT subtitle track into a video container (mov_text for MP4, srt for MKV) without re-encoding the video stream.

輸入參數titlelanguagevideoPath必填outputPath必填subtitlesPath必填

change_speed

Change video and audio playback speed (such as 2x for fast forward or 0.5x for slow motion) with pitch correction.

輸入參數speed必填inputPath必填muteAudiooutputPath必填

reformat_aspect_ratio

Change video aspect ratio to 9:16 vertical, 1:1 square, or 4:5 portrait. Adds blurred video borders, solid padding, or center crops.

輸入參數modepadColorinputPath必填blurAmountoutputPath必填targetRatiohardwareAcceleration

trim_silence

Detect and remove silent pauses from audio or video files. Preserves video & audio lip-sync in 'start_end' mode. Returns original duration and seconds saved.

輸入參數modeinputPath必填outputPath必填thresholdDbminDurationSeconds

create_split_screen

Combine two video files into a split-screen video. Stacks clips vertically (1080x1920 for Reels and TikTok) or places them side-by-side. Supports audio mixing and subtitle embedding.

輸入參數layoutoutputPath必填audioSourcesubtitlesPathfirstVideoPath必填secondVideoPath必填hardwareAcceleration

burn_subtitles

Hardcode/burn subtitles directly into video frames with customizable font size, colors, and positioning. Unlike soft subtitles, burned subtitles render on all platforms including TikTok, Instagram Reels, and YouTube Shorts.

輸入參數marginVfontSizefontColorvideoPath必填outputPath必填outlineColoroutlineWidthsubtitlesPath必填hardwareAcceleration

extract_keyframes

Extract multiple representative frames across a video's timeline. In 'montage' mode, merges frames into a single contact-sheet grid image and inlines base64 for vision models to inspect the whole video at once.

輸入參數countlayoutinputPath必填outputPath必填includeBase64

normalize_audio

Normalize audio loudness using the broadcast standard EBU R128 (loudnorm). Supports -16 LUFS (podcasts/Reels), -14 LUFS (YouTube), and optional voice clarity enhancement (80Hz high-pass to remove mic rumble). Works on audio or video files.

輸入參數inputPath必填outputPath必填targetLufstargetPeakDbvoiceClarity

add_overlay

Place a watermark image, logo PNG, or branding graphic over a video with customizable position, padding, scaling, and opacity.

輸入參數opacitypaddingpositionvideoPath必填outputPath必填scaleWidthoverlayPath必填hardwareAcceleration

mux_media

Combine or replace video and audio streams. Takes a video file and an audio track, with optional audio delay offset, stream-copy mode for zero quality loss, and 'replace' or 'add' stream mapping.

輸入參數modeshortestaudioPath必填videoPath必填outputPath必填streamCopyVideoaudioOffsetSecondshardwareAcceleration

detect_scenes

Detect video cuts and scene transitions. Returns structured timestamps, scene durations, and cut boundaries as JSON, with optional contact-sheet image preview for vision models.

輸入參數inputPath必填thresholdoutputPathincludeBase64minDurationSeconds

版本歷史

4
  1. v0.6.0最新Nov 5, 2026
  2. v0.5.1Nov 3, 2026
  3. v0.5.0Oct 23, 2026
  4. v0.4.2Oct 22, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分