FFmpeg MCP Server

Model Context Protocol (MCP) server that provides 40+ advanced FFmpeg tools for video/audio processing, analysis, and streaming

Features

Media Analysis & Probing (7 tools)

• get_media_info — Comprehensive metadata (codecs, bitrates, resolution, fps, etc.)
• get_video_resolution — Width, height, aspect ratio
• get_duration — File duration in seconds & formatted
• list_streams — All video, audio, subtitle streams
• get_frame_count — Total frame count
• detect_scene_changes — Scene cut detection with timestamps
• get_keyframes — Keyframe timestamp listing

Format Conversion (5 tools)

• convert_video — Full codec/quality control (x264, x265, VP9, AV1, etc.)
• convert_audio — Audio format conversion (MP3, AAC, FLAC, WAV, OGG, etc.)
• convert_to_gif — High-quality GIF with palette optimization
• batch_convert — Bulk convert entire directories
• extract_audio — Extract audio track from video

Video Editing (10 tools)

• trim_video — Cut segments by time
• merge_videos — Concatenate multiple videos
• resize_video — Scale to any resolution
• change_speed — Speed up / slow down with audio sync
• extract_frames — Export frames as images
• create_video_from_images — Image sequence → video
• rotate_video — 90°, 180°, 270° or arbitrary angle
• crop_video — Crop a region
• generate_thumbnail — Extract frame as image
• add_thumbnail — Embed poster image in MP4

Audio Processing (7 tools)

• adjust_volume — Volume control (factor, dB, percentage)
• normalize_audio — EBU R128 loudness normalization
• mix_audio — Overlay/replace audio tracks
• remove_audio — Strip all audio
• add_fade_audio — Fade in/out effects
• generate_waveform — Audio waveform visualization
• generate_spectrogram — Spectrogram image generation

Visual Effects & Filters (7 tools)

• add_text_overlay — Text/watermark with position, timing, styling
• add_image_overlay — Logo/watermark image overlay
• apply_video_filter — Any FFmpeg filter (blur, sharpen, eq, hue, etc.)
• add_fade — Video fade in/out
• picture_in_picture — PiP effect with two videos
• side_by_side — Horizontal/vertical split view
• create_slideshow — Image slideshow with transitions (fade, wipe, slide)

Subtitles (3 tools)

• extract_subtitles — Extract subtitle tracks (SRT, ASS, VTT)
• burn_subtitles — Hardcode subtitles into video
• add_subtitle_track — Add soft subtitles with language tags

Streaming (4 tools)

• create_hls_stream — Generate HLS segments + playlist
• create_dash_stream — Generate DASH manifest + segments
• create_adaptive_hls — Multi-bitrate adaptive streaming (1080p/720p/480p/360p)
• stream_to_rtmp — Stream to YouTube Live, Twitch, etc.

Advanced Processing (14 tools)

• two_pass_encode — Optimal bitrate distribution
• stabilize_video — Shake reduction (vidstab)
• denoise_video — Noise reduction (hqdn3d, nlmeans)
• deinterlace_video — Interlaced → progressive
• change_framerate — FPS conversion with motion interpolation
• compress_video — Target file size or CRF compression
• add_metadata — Add/modify tags (title, artist, year, etc.)
• remove_metadata — Strip all metadata
• reverse_video — Play video backwards
• create_mosaic — Video grid layout (2x2, 3x2, etc.)
• run_custom_ffmpeg — Execute any custom FFmpeg command
• get_ffmpeg_version — FFmpeg version info
• list_supported_formats — All supported formats
• list_supported_codecs — All supported codecs

Prerequisites

• Python 3.10+
• FFmpeg installed and available on PATH
  • Windows: winget install ffmpeg or download from https://ffmpeg.org/download.html
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg

Installation

cd ffmpeg-mcp
pip install -r requirements.txt

Usage

Manual Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "python",
      "args": ["C:/path/to/ffmpeg-mcp/server.py"]
    }
  }
}

Project Structure

ffmpeg-mcp/
├── server.py           # MCP server entry point
├── utils.py            # Shared utilities (run_command, probe, validation)
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project metadata
├── README.md           # This file
└── tools/
    ├── __init__.py     # Tool registration
    ├── probe.py        # Media analysis & probing tools
    ├── convert.py      # Format conversion tools
    ├── video.py        # Video editing tools
    ├── audio.py        # Audio processing tools
    ├── effects.py      # Visual effects & filter tools
    ├── subtitles.py    # Subtitle management tools
    ├── streaming.py    # Streaming (HLS/DASH/RTMP) tools
    └── advanced.py     # Advanced processing tools

Examples

Analyze a video

"Get detailed info about this video: C:/Videos/test.mp4"

Convert video

"Convert test.mp4 to MKV with H.265 codec at CRF 20 quality"

Create GIF

"Create a GIF from the video between 5s and 15s, 320px wide"

Compress video

"Compress this video to under 50MB"

Adaptive streaming

"Create an HLS stream with 1080p, 720p, and 480p quality levels"

Stabilize shaky video

"Stabilize this shaky video"

License

MIT