MCP server for video/audio processing via FFmpeg - convert, compress, trim, extract audio, add subtitles
🎬 ffmpeg-mcp
A powerful MCP server for video and audio processing through FFmpeg
Integrate FFmpeg with Claude, Dive, and other MCP-compatible AI systems. Convert, compress, trim videos, extract audio, and more — all through natural language.
Features • Installation • Tools • Usage • Configuration
✨ Features
📊 Media Information
🔄 Format Conversion
🗜️ Video Compression
✂️ Video Trimming
|
🎵 Audio Extraction
🎞️ Advanced Features
📝 Subtitles
|
🚀 Installation
Prerequisites
Install FFmpeg on your system:
| Platform | Command |
|---|---|
| 🪟 Windows | winget install FFmpeg |
| 🍎 macOS | brew install ffmpeg |
| 🐧 Linux | sudo apt install ffmpeg |
Getting Started
Add the following config to your MCP client:
{
"mcpServers": {
"ffmpeg": {
"command": "uvx",
"args": ["ffmpeg-mcp-lite"]
}
}
}
MCP Client Configuration
Dive
- Open Dive Desktop
- Click "+ Add MCP Server"
- Paste the config provided above
- Click "Save" and you're ready!
Claude Code
Use the Claude Code CLI to add the ffmpeg MCP server:
claude mcp add ffmpeg uvx ffmpeg-mcp-lite
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"ffmpeg": {
"command": "uvx",
"args": ["ffmpeg-mcp-lite"]
}
}
}
Cursor
Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.
VS Code / Copilot
Install via the VS Code CLI:
code --add-mcp '{"name":"ffmpeg","command":"uvx","args":["ffmpeg-mcp-lite"]}'
Windsurf
Follow the configure MCP guide using the standard config from above.
Manual Installation
pip install ffmpeg-mcp-lite
Or with uv:
uv pip install ffmpeg-mcp-lite
🛠️ Available Tools
All tools are prefixed with ffmpeg_ to avoid naming conflicts with other MCP servers.
📊 Media Information
| Tool | Description |
|---|---|
ffmpeg_get_info |
Get comprehensive video/audio metadata
|
🔄 Conversion & Compression
| Tool | Description |
|---|---|
ffmpeg_convert |
Convert video/audio to different formats
|
ffmpeg_compress |
Compress video to reduce file size
|
✂️ Editing
| Tool | Description |
|---|---|
ffmpeg_trim |
Trim video to extract a segment
|
ffmpeg_merge |
Concatenate multiple videos into one
|
🎵 Audio & Frames
| Tool | Description |
|---|---|
ffmpeg_extract_audio |
Extract audio track from video
|
ffmpeg_extract_frames |
Extract frames as images
|
📝 Subtitles
| Tool | Description |
|---|---|
ffmpeg_add_subtitles |
Burn-in subtitles to video (hardcode)
|
💡 Usage Examples
Get Media Information
"Get info about /path/to/video.mp4"
"What's the resolution and duration of this video?"
"Show me the codec information for my video"
Convert Videos
"Convert video.mp4 to WebM format"
"Convert this video to MKV with h265 codec"
"Convert and scale to 1280x720"
Compress Videos
"Compress video.mp4 with medium quality"
"Compress this video to reduce file size, use fast preset"
"Compress with high quality and scale to 1920:-1"
Trim Videos
"Trim video.mp4 from 00:01:00 to 00:02:30"
"Cut the first 30 seconds from this video"
"Extract a 1-minute clip starting at 5:00"
Extract Audio
"Extract audio from video.mp4 as MP3"
"Get the audio track in AAC format with 192k bitrate"
"Extract audio as FLAC for best quality"
Extract Frames
"Extract one frame every 5 seconds from video.mp4"
"Get 10 frames evenly distributed from this video"
"Extract frames as PNG images"
Merge Videos
"Merge video1.mp4 and video2.mp4 together"
"Concatenate these three videos into one"
Add Subtitles
"Add subtitles.srt to video.mp4"
"Burn in Chinese subtitles with shadow style"
"Add subtitles with font size 32 and glow effect"
🔧 Configuration
Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| FFMPEG_PATH | Path to ffmpeg binary | ffmpeg |
| FFPROBE_PATH | Path to ffprobe binary | ffprobe |
| FFMPEG_OUTPUT_DIR | Default output directory | ~/Downloads |
Custom Configuration
{
"mcpServers": {
"ffmpeg": {
"command": "uvx",
"args": ["ffmpeg-mcp-lite"],
"env": {
"FFMPEG_OUTPUT_DIR": "/path/to/output"
}
}
}
}
🏗️ Architecture
Built With
- FFmpeg - Video/audio processing engine
- FastMCP - MCP Python framework
- asyncio - Async subprocess execution
- Python 3.10+ - Type hints and modern features
Key Features
- ✅ Async Processing: Non-blocking FFmpeg execution
- ✅ Type Safe: Full type hints with mypy validation
- ✅ Well Tested: 31 test cases with pytest
- ✅ Cross Platform: Works on Windows, macOS, Linux
- ✅ Modular Design: One file per tool
🤝 Contributing
Contributions are welcome!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development
# Clone and install
git clone https://github.com/kevinwatt/ffmpeg-mcp-lite.git
cd ffmpeg-mcp-lite
uv sync
# Run tests
uv run pytest
# Type checking
uv run mypy src/
# Linting
uv run ruff check src/
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- FFmpeg - The powerful multimedia framework
- Anthropic - For the Model Context Protocol
- Dive - MCP-compatible AI platform