ffmpeg-mcp-server 🎬

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

🧪 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.