ffmpeg-mcp

★ 5

from yubraaj11

A Python package for media processing using FFmpeg and FastMCP.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup

#git #video-editing

ffmpeg-mcp

ffmpeg-mcp 🎬⚡

Edit video and audio by just talking to your AI assistant.

ffmpeg-mcp is a Model Context Protocol server that puts the full power of FFmpeg behind a clean set of tools your LLM can call — clip, crop, scale, overlay, concatenate with transitions, extract frames/audio, make GIFs, and more. No command-line flags to memorize.

✨ Why ffmpeg-mcp?

FFmpeg is incredibly powerful and incredibly hard to remember. ffmpeg-mcp hands that power to your AI assistant so you can say what you want in plain English:

"Grab the first 10 seconds of demo.mov, scale it to 1080p, slap my logo in the top-right corner, and turn it into a GIF."

…and the model orchestrates the right tools for you. Each tool is a small, validated Python function — easy to read, reuse, and extend.

🗣️ Natural-language video editing — works in any MCP client (Claude Desktop, Cursor, Cline, …)
🧱 12 focused tools — composable building blocks instead of one giant black box
✅ Input validation built in — paths are checked for existence, emptiness, and validity before FFmpeg runs
🧩 Hackable — add a new tool by writing one function and registering it

🛠️ Available Tools

Tool	What it does	Key parameters
`get_video_metadata`	Probe a file for streams, codecs, duration, etc.	`input_video_path`
`extract_frames`	Save frames as images (evenly, by interval, or 1/sec)	`input_video_path`, `number_of_frames?`, `timestamp_offset?`
`extract_audio`	Pull audio out to a `.wav` file	`input_video_path`
`scale_video`	Upscale to `1080p` / `2k` / `4k`, aspect-preserving	`input_video_path`, `resolution="1080p"`
`crop_video`	Crop to a region	`input_video_path`, `width`, `height`, `x_offset`, `y_offset`, `safe_crop`
`clip_video`	Cut a sub-clip by start + duration	`input_video_path`, `start_timestamp`, `duration`
`make_gif`	Turn a segment into an optimized GIF	`input_video_path`, `start_timestamp`, `duration`
`overlay_image`	Composite an image (logo/watermark) with timing & opacity	`input_video_path`, `overlay_image_path`, `positioning`, `opacity`, `start_time`, `duration`
`overlays_video`	Overlay a (looping) video onto another	`input_video_path`, `overlay_video_path`, `positioning`, `scale`
`trim_and_concat_operation`	Trim multiple clips and stitch them together	`inputs: [{path, start_time?, end_time?}]`, `width`, `height`
`get_normalized_clips`	Normalize clips to a common res/fps/codec (in parallel)	`input_video_clips`, `resolution`, `frame_rate`, `crf`
`concat_clips_with_transition`	Concatenate clips with an `xfade` transition	`input_video_clips`, `transition_type="fade"`, `transition_duration`

? marks optional parameters. concat_clips_with_transition supports many transitions — fade, wipeleft, slideup, circlecrop, dissolve, pixelize, radial, and dozens more.

🧰 Project Layout

ffmpeg_mcp/
├── main.py              # MCP server entry point — registers all tools
├── services/            # one module per tool
├── configs/             # colored logging setup
└── exceptions/          # structured error messages
utils/                   # validation decorators & helpers

Every tool returns either the output file path or a structured JSON error (status, error_type, message, time), so failures are easy for the model to read and recover from.

🤝 Contributing

Contributions are very welcome! Adding a tool is roughly:

Write a function in ffmpeg_mcp/services/your_tool.py.
Export it from ffmpeg_mcp/services/__init__.py.
Register it in main.py with mcp.tool(name_or_fn=your_tool).

Please run the linter before opening a PR:

uv run ruff check .

Found a bug or have an idea? Open an issue — and if this project saves you from another ffmpeg man-page dive, consider leaving a ⭐.

📚 Built With

fastmcp — the MCP server framework
ffmpeg-python — Python bindings for FFmpeg
pydantic — data validation
colorlog — colored logs

Copy & paste — that's it

git clone https://github.com/yubraaj11/ffmpeg-mcp.git
cd ffmpeg-mcp
uv sync --frozen

Before it works, you'll need: PYTHONPATH

📦 Requirements

Python 3.12+
FFmpeg installed and on your PATH (provides ffmpeg + ffprobe)
uv package manager

Verify FFmpeg is available:

ffmpeg -version

🚀 Quick Start

1. Clone & install

git clone https://github.com/yubraaj11/ffmpeg-mcp.git
cd ffmpeg-mcp
uv sync --frozen

2. Connect it to your MCP client

Point your client at the server using the snippets below. Replace /path/to/ffmpeg-mcp with the absolute path to your clone.

Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json)

{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" }
    }
  }
}

Cline (VS Code)

{
  "mcpServers": {
    "ffmpeg-mcp": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" },
      "transportType": "stdio"
    }
  }
}

3. Restart your client and start editing

"Extract 5 evenly-spaced frames from intro.mp4."

"Make a 3-second GIF from clip.mov starting at 12s."

"Concatenate a.mp4, b.mp4, and c.mp4 with a 1-second wipeleft transition between them."

Processed files are written under ffmpeg_mcp/processed_elements/.