FFmpeg MCP Server

io.github.Ashutos1997Published by GitHub account Ashutos1997v0.6.0Updated Nov 5, 2026

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

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Local MCP server that runs FFmpeg and FFprobe so an assistant can inspect, convert, trim, compress and caption video and audio files.

What you can do
  • Inspect media: probe files for codecs, resolution, bitrate and duration, and detect scene cuts with timestamps.
  • Convert and edit: convert formats with web, WebM and GIF presets, trim segments, join files, change speed, and mux or replace audio tracks.
  • Adapt for social: reformat to 9:16, 1:1 or 4:5, build split-screen reels, compress to target file sizes, and add watermarks.
  • Audio work: extract audio (including a 16kHz mono WAV preset for speech models), normalize loudness to EBU R128 targets, and trim silence.
  • Subtitles: embed SRT or VTT tracks or burn them into frames with custom styling.
  • Visual previews: grab thumbnails, keyframe contact sheets and waveform PNGs, returned as file paths…
When to use it
Useful when an assistant needs to work with local video or audio files: preparing clips for social platforms, shrinking files to upload limits, extracting audio for transcription, or letting a vision model look at frames. It suits editing and media-prep workflows where valid FFmpeg commands matter more than hand-written flags.
Requirements
Runs as a local stdio process, typically launched with npx from the npm package. Needs Node.js 18 or newer and FFmpeg plus FFprobe installed on the machine (libass on Linux for subtitle work). No accounts, API keys or environment variables are declared. Hardware encoding depends on the local GPU and drivers.
Before you install
It runs FFmpeg on files on your machine, so it can read any path the assistant is given and write new output files; review output paths before running. Some tools overwrite or create files at the chosen destination, and compress_video is stated not to modify the original. Media content, including base64 frames, is passed back into the model context.

Installation

In SourceWeft

  1. Open FFmpeg MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit c18838b

Tools

19

media_probe

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

ParametersinputPathrequired

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.

ParameterscrffpspresetinputPathrequiredoutputPathrequiredresolutionhardwareAcceleration

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.

ParametersendTimedurationinputPathrequiredstartTimerequiredoutputPathrequiredaccurateReencode

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.

ParametersformatbitrateinputPathrequiredoutputPathrequired

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.

ParametersinputPathrequiredtimestampoutputPathrequiredresolutionincludeBase64

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.

ParameterscrfpresetmaxWidthinputPathrequiredoutputPathrequiredtargetSizeMBhardwareAcceleration

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.

ParametersmodeinputPathsrequiredoutputPathrequired

generate_waveform

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

ParameterscolorscalewidthheightinputPathrequiredoutputPathrequiredincludeBase64

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.

ParameterstitlelanguagevideoPathrequiredoutputPathrequiredsubtitlesPathrequired

change_speed

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

ParametersspeedrequiredinputPathrequiredmuteAudiooutputPathrequired

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.

ParametersmodepadColorinputPathrequiredblurAmountoutputPathrequiredtargetRatiohardwareAcceleration

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.

ParametersmodeinputPathrequiredoutputPathrequiredthresholdDbminDurationSeconds

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.

ParameterslayoutoutputPathrequiredaudioSourcesubtitlesPathfirstVideoPathrequiredsecondVideoPathrequiredhardwareAcceleration

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.

ParametersmarginVfontSizefontColorvideoPathrequiredoutputPathrequiredoutlineColoroutlineWidthsubtitlesPathrequiredhardwareAcceleration

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.

ParameterscountlayoutinputPathrequiredoutputPathrequiredincludeBase64

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.

ParametersinputPathrequiredoutputPathrequiredtargetLufstargetPeakDbvoiceClarity

add_overlay

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

ParametersopacitypaddingpositionvideoPathrequiredoutputPathrequiredscaleWidthoverlayPathrequiredhardwareAcceleration

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.

ParametersmodeshortestaudioPathrequiredvideoPathrequiredoutputPathrequiredstreamCopyVideoaudioOffsetSecondshardwareAcceleration

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.

ParametersinputPathrequiredthresholdoutputPathincludeBase64minDurationSeconds

Version history

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

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts