ffmpeg-mcp

✨ 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

> `?` 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.

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/`.

🧰 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