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 分