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

Related MCP server: FFmpeg MCP Server

🛠️ Available Tools

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

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

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

{
  "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/.

🧰 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:

1. Write a function in ffmpeg_mcp/services/your_tool.py.

2. Export it from ffmpeg_mcp/services/__init__.py.

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