gamhoi/mcp-ffmpeg-tools
If you are the rightful owner of mcp-ffmpeg-tools and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
mcp-ffmpeg-tools is an open-source Python MCP server that allows LLMs to execute FFmpeg commands, receive execution results, and validate commands against FFmpeg source code.
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
- Download FFmpeg from ffmpeg.org
- Extract the archive to a location of your choice
- Add the
bindirectory 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
- Clone the repository:
git clone https://github.com/gamhoi/mcp-ffmpeg-tools.git
cd mcp-ffmpeg-tools
- Install using uv:
uv venv
uv pip install -e .
The installation process will:
- Verify that FFmpeg is installed and accessible in your system PATH
- Download the corresponding FFmpeg source code for validation
- 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/mcpassumes the MCP server runs locally. If you're running in a remote or networked environment, replacelocalhostwith 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/
