Ffmpeg MCP Lite

🚀 ffmpeg-mcp

A powerful MCP server for video and audio processing through FFmpeg. It integrates FFmpeg with Claude, Dive, and other MCP-compatible AI systems, enabling users to convert, compress, trim videos, extract audio, and more via natural language.

Features • Installation • Tools • Usage • Configuration

✨ Features

📊 Media Information

• Retrieve comprehensive metadata, including duration, resolution, codecs, bitrate, and stream details.
• Output in JSON format.

🔄 Format Conversion

• Convert between various formats such as MP4, MKV, WebM, MOV, etc.
• Support custom video and audio codecs.
• Scale the resolution as needed.

🗜️ Video Compression

• Offer quality presets (low/medium/high).
• Control the encoding speed.
• Optimize with H.264.
• Provide size reduction statistics.

✂️ Video Trimming

• Specify precise start and end times or duration for cuts.
• Use stream copy for fast processing without re-encoding.

🎵 Audio Extraction

• Support multiple audio formats like MP3, AAC, WAV, FLAC, OGG, Opus.
• Control the bitrate for high-quality output.

🎞️ Advanced Features

• Merge multiple videos into one.
• Extract frames as images in JPG, PNG, BMP formats.
• Extract frames based on intervals or counts.

📝 Subtitles

• Burn-in SRT/ASS/VTT subtitles with multiple styles.
• Customize the font size.
• Work well with Whisper MCP.

🚀 Installation

Prerequisites

Install FFmpeg on your system:

Getting Started

Add the following config to your MCP client:

{
  "mcpServers": {
    "ffmpeg": {
      "command": "uvx",
      "args": ["ffmpeg-mcp-lite"]
    }
  }
}

MCP Client Configuration

{
  "mcpServers": {
    "ffmpeg": {
      "command": "uvx",
      "args": ["ffmpeg-mcp-lite"]
    }
  }
}

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

🔄 Conversion & Compression

✂️ Editing

🎵 Audio & Frames

📝 Subtitles

💻 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

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!

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. 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

⬆ Back to Top