MCP Ffmpeg Tools

mcp-ffmpeg-tools

An open-source Python MCP (Model-Command Protocol) server designed to enable Large Language Models (LLMs) to execute FFmpeg commands, receive execution results, and validate commands against FFmpeg source code.

Prerequisites

Before installing mcp-ffmpeg-tools, you need to have FFmpeg installed on your system:

Windows

1. Download FFmpeg from ffmpeg.org
2. Extract the archive to a location of your choice
3. Add the bin directory to your system PATH

macOS

brew install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Linux (Fedora)

sudo dnf install ffmpeg

Features

• Execute FFmpeg commands through an MCP interface
• Receive detailed execution results and error messages
• Access FFmpeg source code for command correction
• Cross-platform support (Windows, macOS, Linux)
• Environment management using uv

Installation

1. Clone the repository:

git clone https://github.com/gamhoi/mcp-ffmpeg-tools.git
cd mcp-ffmpeg-tools

1. Install using uv:

uv venv
uv pip install -e .

The installation process will:

1. Verify that FFmpeg is installed and accessible in your system PATH
2. Download the corresponding FFmpeg source code for validation
3. Install the Python package and its dependencies

If FFmpeg is not found or the source code download fails, the installation will fail.

Usage

Usage with Claude Desktop

Add the following configuration to your Claude Desktop settings:

{
    "mcpServers": {
        "mcp-ffmpeg-tools": {
            "command": "uv",
            "args": [
                "--directory",
                "PATH_TO/mcp-ffmpeg-tools",
                "run",
                "ffmpeg-tools"
            ]
        }
    }
}

Running Tests

uv run python3 client/test.py

Prompt Examples

Base prompt

Help me perform media conversion tasks using FFmpeg. You can:
- use tool:execute_ffmpeg to run FFmpeg commands
- use tool:execute_ffprobe to inspect results (e.g., resolution, bitrate)
- use tool:get_screenshot to inspect results (e.g., video layout, quality)
- use tool:ls_ffmpeg_source_code and tool:get_ffmpeg_source_code to validate commands using FFmpeg source code

Extract video and audio

Extract all media streams from the file 'YOU_FILE_PATH' and save outputs to 'YOU_OUTPUT_PATH'

Overlay 2 videos

Overlay file1 'YOU_FILE_PATH_1' and file2 'YOU_FILE_PATH_2', using file1 as the background. Scale file2 down to half its original resolution and position it at the top-right corner of file1. Save the output to 'YOUR_OUTPUT_PATH'.

Run with Docker

You can run the MCP FFmpeg Tools in HTTP mode via Docker. This allows you to expose the MCP API (/mcp) over an HTTP port for use by clients.

Option 1 — Pull from Docker Hub

You can directly pull and run the official image from Docker Hub:

docker pull gamhoi/mcp-ffmpeg-tools:latest

Run it on port 8000:

docker run -d -p 8000:8000 gamhoi/mcp-ffmpeg-tools:latest --port 8000

Add the following configuration to your Claude Desktop settings:

{
    "mcpServers": {
        "mcp-ffmpeg-tools-http": {
            "type": "streamableHttp",
            "url": "http://localhost:8000/mcp"
        }
    }
}

Note: The default URL http://localhost:8000/mcp assumes the MCP server runs locally. If you're running in a remote or networked environment, replace localhost with your host IP or domain name.

Option 2 — Build locally

If you prefer to build from Dockerfile:

docker build -t mcp-ffmpeg-tools .

Accessing local files

By default, the container’s internal ffmpeg cannot access your local files outside Docker. To allow it to process local videos, you must mount a host directory into the container.

Example:

docker run -d -p 8000:8000 -v /local_media:/media gamhoi/mcp-ffmpeg-tools:latest --port 8000

In this example:

• You can put your local video files on: /local_media/sample.mp4
• Inside the container, the same file will be accessible as: /media/sample.mp4

So when you ask the LLM to process a local file, you should do like this:

Extract all media streams from the file /media/sample.mp4 and save outputs to /media/