ffmpeg-mcp 🎬⚡

A Python package for media processing using FFmpeg and FastMCP. It enables building microservices that handle video/audio tasks with clean, reusable interfaces.

📖 Overview

This project provides a framework for handling media processing tasks using:

1. FFmpeg — A powerful multimedia framework for processing audio and video files

2. FastMCP — A high-performance framework for building microservices

🛠️ Available Tools

1. Metadata & Frames

• get_video_metadata

  • param(s):

    • input_video_path: str

• extract_frames

  • params:

    • input_video_path: str | Path

    • number_of_frames: int

    • frame_timestamps: int (eg: 5s, 10s, 15s, ...)

2. Audio

• extract_audio

  • param(s):

    • input_video_path: str

3. Video Scaling & Resizing

• scale_video

  • params:

    • input_video_path: str

    • resolution: Optional[str]

4. Overlay Operations

• overlay_image

  • params:

    • input_video_path: str

    • overlay_image_path: str

    • positioning: Literal[top_left, bottom_left, top_right, bottom_right, center, top_center, bottom_center] = 'top_right'

    • scale: tuple[int, int] | None = (100, 100)

    • keep_audio: bool = True

    • opacity: float | None = None (range 0.0–1.0)

    • start_time: float = 0.0 (in seconds)

    • duration: float | None = None (in seconds; None = until end of video)

• overlays_video

  • params:

    • input_video_path: str

    • overlay_video_path: str

    • positioning: Literal[top_left, bottom_left, top_right, bottom_right] = 'top_left'

5. Video Editing

• clip_video

  • params:

    • input_video_path: str

    • start_timestamp

    • duration: int

• crop_video

  • params:

    • input_video_path

    • safe_crop: bool

    • height: int

    • width: int

    • x_offset: int

    • y_offset: int

• trim_and_concatenate

  • params:

    • input_video_path

    • number_of_trims: int

    • trim_timestamp: List[(start, end), (start, end), ...]

• make_gif

  • params:

    • input_video_path

    • start_timestamp

    • duration

6. Concatenation & Transitions

• concatenate_videos

  • param(s):

    • file_list: list[Path]

• normalize_video_clips

  • params:

    • input_video_clips: List[str]

    • resolution: tuple default (1280, 720)

    • frame_rate: int default 30

    • crf: int default 23

    • audio_bitrate: str default 128k

    • preset: str default fast

• concat_clips_with_transition

  • params:

    • input_video_clips: List[str]

    • transition_types: str default fade (e.g., fade, wipeleft, rectcrop, coverup, etc.)

    • transition_duration: float default 2

🧰 Utilities

The utils folder contains helper functions and decorators to enhance the functionality and robustness of the media processing tools.

a. Decorators

• validate_input_video_path A decorator that checks if the video path exists, is non-empty, and is a valid video file. This ensures that all video processing functions receive a valid input file.

📦 Requirements

• Python 3.12 or higher

• uv (package manager)

• FFmpeg installed on the system

🚀 Usage

The package can be used to build media processing microservices that leverage the power of FFmpeg through a Python interface.

1. Clone this repo

git clone git@github.com:yubraaj11/ffmpeg-mcp.git

2. Sync the project

uv sync --frozen

3. Use via MCP - Cline config

{
  "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"
    }
  }
}

📚 Dependencies

• ffmpeg-python — Python bindings for FFmpeg

• fastmcp — Framework for building microservices

• colorlog — Colored logging output

• fastapi — Web framework for building APIs

• pydantic — Data validation and settings management