ffmpeg-mcp-server
Provides tools for inspecting, trimming, reframing, extracting audio from, and burning subtitles into media files using ffmpeg and ffprobe.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ffmpeg-mcp-server Trim clip.mp4 to 00:00:30–00:01:00 and reframe it to 9:16 for Shorts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 viaffprobein clean JSON.✂️ Frame-Accurate Clip Trimming (
trim_clip): Cuts segments with millisecond-accurate timestamps (HH:MM:SS.mmmor 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.srtsubtitle files from structured cue arrays and burns them into video with customizable font size and margin styling.🎵 Audio Extraction & Normalization (
extract_audio): Extracts cleanmp3,wav,flac, orm4atracks 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=Truesupport on every mutative tool so agents can preview exactffmpegargv arrays before execution.
Related MCP server: ffmpeg-mcp
🚀 Quick Start
Prerequisites
Python 3.10+
ffmpegandffprobeinstalled on your systemPATH(sudo apt install ffmpegorbrew 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 |
| Inspect container duration, streams, resolution, FPS, and codecs via | Yes |
| Cut a media segment between | Yes |
| Reframe video to | Yes |
| Extract audio stream to | Yes |
| Build a validated | No (Pure file/string) |
| Burn an | 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 toolsburn_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Turn any video or audio link into files, transcripts and metadata, right from your AI agent.
Related MCP Servers
- AlicenseBqualityBmaintenanceProvides video and audio manipulation tools powered by FFmpeg, enabling AI assistants to perform media operations such as cutting, converting, and removing silence.6453 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseBqualityCmaintenanceProvides Claude Code with local ffmpeg-based tools to probe, trim, concat, transform, overlay, mix audio, render JSON timelines, and run automated QA on video files—no API key required.9Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI agents to programmatically edit videos via FFmpeg, providing tools for probing, trimming, concatenating, timeline composition, LUT generation/application, rendering, and edit verification over MCP.162MIT