ffmpeg-mcp

You can build practical media processing microservices with ffmpeg-mcp, a Python-based framework that leverages FFmpeg through a clean MCP interface. It lets you extract metadata, pull frames, transcode, scale, overlay images, concatenate videos, and more, all while providing a high-performance, reusable service layer.

How to use

You will run the ffmpeg-mcp server as a local MCP service and connect to it from an MCP client. The server exposes a set of media processing tools implemented as Python functions that you can invoke through the MCP workflow. Use the standard MCP runtime to launch the local server, then configure your client to call the available endpoints or functions by name. Your client can chain operations such as extracting audio, resizing video, overlaying an image, and exporting a GIF, all within a single, cohesive workflow.

How to install

# Prerequisites
# - Python 3.12 or higher
# - uvx package manager
# - FFmpeg installed on the system

# 1) Clone the project
git clone git@github.com:yubraaj11/ffmpeg-mcp.git

# 2) Sync the project for local development
uv sync --frozen

# 3) Run the MCP server locally using the provided CLI command
# This example uses the standard MCP stdio config shown in the usage snippet
uv
# Then follow the runtime instructions to execute main.py from the ffmpeg-mcp directory

# 4) Connect your MCP client to the local server using the recommended config
# (see the MCP JSON configuration example in the usage section)

Configuration and run

The server is typically run as a local MCP service via a command that initializes the runtime and executes the main Python entry point. You will specify your Python path and the directory to the ffmpeg-mcp package, along with the script to run. The example below shows a complete MCP stdio configuration you can use to start the server from your MCP client. Adjust the path values to match your local environment.

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

Notes on usage and tips

• Ensure FFmpeg is installed and accessible in your system PATH. The tools rely on FFmpeg bindings to perform media processing tasks.
• The package uses a decorator to validate input video paths to help catch issues early in the processing pipeline.
• If you plan to run multiple services or services on different ports, you can replicate the MCP config for each instance and adjust the directory and entry points as needed.

Security and troubleshooting

• Keep your environment variables secure and restrict access to the MCP runner when running locally. Use the PYTHONPATH entry cautiously and avoid exposing sensitive paths.
• If a processing step fails, check the FFmpeg command outputs and log messages provided by the colorized logging. Validate input paths before submission to the pipeline to avoid cascading failures.

Available tools

get_video_metadata

Retrieves metadata for a given input video, such as duration, dimensions, and codec information.

extract_frames

Extracts a specified number of frames at given timestamps from a video.

extract_audio

Extracts the audio track from a video file.

scale_video

Resizes or scales a video to a target resolution.

overlay_image

Overlays an image onto a video at a defined position with optional scaling and opacity.

overlays_video

Overlays a video onto another video at a defined position.

clip_video

Cuts a segment from the input video based on start time and duration.

crop_video

Crops a video to a specified width, height and offset.

trim_and_concatenate

Trims multiple segments from a video and concatenates them in sequence.

make_gif

Converts a video segment into an animated GIF.

concatenate_videos

Joins multiple video clips in the given order.

normalize_video_clips

Normalizes a set of video clips to a target resolution, frame rate, and encoding settings.

concat_clips_with_transition

Concatenates clips with transitions between them (e.g., fade, wipe).

validate_input_video_path

Decorator to ensure the provided video path exists and points to a valid video file.