mcp-ffmpeg-tools
About
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.
Details
- Author
- gamhoi
- Downloads
- 452
- Categories
- Other
Jump to
- Execute FFmpeg commands through an MCP interface
- Receive detailed execution results and error messages
- Validate commands using FFmpeg source code
- Cross-platform support (Windows, macOS, Linux)
- Environment management using uv
- Docker support with HTTP mode and file mounting
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
mcp-ffmpeg-toolsCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install FFmpeg, then clone the repository, create a virtual environment with uv venv, and install with uv pip install -e .. For Claude Desktop, add the provided JSON configuration specifying the uv command and path. Alternatively, run via Docker with docker pull gamhoi/mcp-ffmpeg-tools:latest and configure the HTTP endpoint.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp-ffmpeg-tools": {
"mcp-ffmpeg-tools": {
"command": "uv",
"args": [
"--directory",
"PATH_TO/mcp-ffmpeg-tools",
"run",
"ffmpeg-tools"
]
}
}
}
}McpServers
{
"mcp-ffmpeg-tools": {
"command": "uv",
"args": [
"--directory",
"PATH_TO/mcp-ffmpeg-tools",
"run",
"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 thebin 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
2. 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/
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
