Skip to main content
Glama

ffmpeg-mcp-server 🎬

CI License: MIT Python 3.10+ MCP Compatible

ffmpeg-mcp-server is a deterministic, security-hardened Model Context Protocol (MCP) server that gives AI coding agents (Claude Code, Cursor, Windsurf, Cline, Gemini) safe, structured tools for inspecting, trimming, reframing (9:16 vertical shorts), extracting audio, and burning dynamic subtitles into video and audio files via ffmpeg and ffprobe.

Unlike raw shell-execution wrappers that expose agents to command injection or destructive path traversal, ffmpeg-mcp-server enforces workspace sandboxing, strict argument validation, argument-list subprocess execution (shell=False), and dry-run command inspection.


✨ Key Features

  • 🔒 Sandboxed Workspace Security: Confines all input/output media operations to an explicit allowed root directory (FFMPEG_MCP_WORKDIR), blocking path traversal (..) and symlink escapes.

  • 📊 Structured Media Probing (probe_media): Extracts duration, resolution, codec, FPS, bitrates, and audio stream metadata via ffprobe in clean JSON.

  • ✂️ Frame-Accurate Clip Trimming (trim_clip): Cuts segments with millisecond-accurate timestamps (HH:MM:SS.mmm or seconds) and configurable stream copy or H.264/AAC re-encoding.

  • 📱 Vertical 9:16 Reframing (convert_aspect_ratio): Automatically computes center-crop or blurred-pad filtergraphs for TikTok, Reels, and YouTube Shorts (9:16, 1:1, 16:9, 4:5).

  • 💬 Deterministic SRT Generator & Subtitle Burn-In (generate_srt, burn_subtitles): Creates valid .srt subtitle files from structured cue arrays and burns them into video with customizable font size and margin styling.

  • 🎵 Audio Extraction & Normalization (extract_audio): Extracts clean mp3, wav, flac, or m4a tracks with optional EBU R128 loudness normalization (loudnorm).

  • 🧪 Zero-Dependency Core & Dry-Run Mode: Built on the Python standard library with a compliant JSON-RPC 2.0 stdio MCP transport, plus dry_run=True support on every mutative tool so agents can preview exact ffmpeg argv arrays before execution.


Related MCP server: ffmpeg-mcp

🚀 Quick Start

Prerequisites

  • Python 3.10+

  • ffmpeg and ffprobe installed on your system PATH (sudo apt install ffmpeg or brew install ffmpeg).

Installation

pip install -e ".[dev]"

Claude Code / Claude Desktop Configuration

Add ffmpeg-mcp-server to your claude_desktop_config.json or .mcp.json:

{
  "mcpServers": {
    "ffmpeg": {
      "command": "ffmpeg-mcp-server",
      "env": {
        "FFMPEG_MCP_WORKDIR": "/path/to/your/media/workspace"
      }
    }
  }
}

Or add it directly in Claude Code CLI:

claude mcp add ffmpeg -- ffmpeg-mcp-server --workdir /path/to/your/media/workspace

🛠️ Available MCP Tools

Tool Name

Description

Supports dry_run

probe_media

Inspect container duration, streams, resolution, FPS, and codecs via ffprobe.

Yes

trim_clip

Cut a media segment between start_time and end_time or duration.

Yes

convert_aspect_ratio

Reframe video to 9:16, 1:1, 16:9, or 4:5 using crop or pad mode.

Yes

extract_audio

Extract audio stream to mp3, wav, flac, or m4a with optional loudnorm.

Yes

generate_srt

Build a validated .srt subtitle file from a list of {start, end, text} cues.

No (Pure file/string)

burn_subtitles

Burn an .srt file into a video with custom font size and alignment.

Yes


🧪 Running Tests

All unit tests run offline without requiring media fixtures or external network calls:

pytest -q
ruff check .

🤝 Contributing & Security

See CONTRIBUTING.md for development setup and pull request guidelines, and SECURITY.md for our security policy and sandboxing invariants.

📄 License

Licensed under the MIT License.

Available Tools

6 tools
burn_subtitlesC

Burn an .srt subtitle file into a video with customizable font size and vertical margin.

Inputs: input_path (required), output_path (required), subtitle_path (required), dry_run, +2 more.

convert_aspect_ratioC

Reframe a video to 9:16, 1:1, 16:9, or 4:5 using crop or pad mode.

Inputs: input_path (required), output_path (required), mode, dry_run, +1 more.

extract_audioC

Extract audio track from media file into mp3, wav, flac, or m4a.

Inputs: input_path (required), output_path (required), dry_run, normalize, +1 more.

generate_srtB

Generate a validated .srt subtitle file inside the workspace from structured cues.

Inputs: cues (required), output_path (required).

probe_mediaB

Inspect media container duration, resolution, codecs, and streams via ffprobe.

Inputs: input_path (required), dry_run.

trim_clipC

Trim a video or audio clip between start_time and end_time/duration.

Inputs: input_path (required), output_path (required), dry_run, duration, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool maps to a distinct ffmpeg operation: probing, trimming, aspect-ratio reframing, audio extraction, SRT generation, and subtitle burning. There is no meaningful overlap; generate_srt (create cues) and burn_subtitles (embed an existing .srt) are clearly differentiated by their descriptions.

    Naming Consistency5/5

    All six tools follow a consistent snake_case verb_noun pattern (probe_media, trim_clip, extract_audio, burn_subtitles, etc.). Verb choices are accurate and predictable, and convert_aspect_ratio is the only longer name but still fits the convention.

    Tool Count5/5

    Six tools is a well-scoped surface for a focused ffmpeg wrapper, with each tool earning its place. Nothing feels redundant or padded, and the set stays comfortably in the ideal 3-15 range.

    Completeness3/5

    Core operations (probe, trim, reframe, audio extract, subtitle create/burn) are covered, but common ffmpeg workflows are absent: concatenation/merging clips, general format transcoding or compression, frame/thumbnail extraction, and overlays/watermarks. These gaps will force agents to work around missing lifecycle operations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables LLMs to safely execute ffmpeg and ffprobe operations by passing arguments as arrays, avoiding shell injection, with support for probe, convert, trim, concat, thumbnail, watermark, speed, loudnorm, and batch processing.
      16,348 npm
      MIT