ffmpeg-mcp-lite 0.2.2

MCP server providing video and audio processing capabilities through FFmpeg

🎬 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 Get comprehensive metadata Duration, resolution, codecs Bitrate and stream details JSON formatted output 🔄 Format Conversion Convert between any formats MP4, MKV, WebM, MOV, etc. Custom video/audio codecs Resolution scaling 🗜️ Video Compression Quality presets (low/medium/high) Encoding speed control H.264 optimization Size reduction stats ✂️ Video Trimming Precise start/end times Duration-based cuts Stream copy (fast) No re-encoding needed

🎵 Audio Extraction Multiple formats supported MP3, AAC, WAV, FLAC, OGG, Opus Bitrate control High quality output 🎞️ Advanced Features Merge multiple videos Extract frames as images Interval or count-based extraction JPG, PNG, BMP, WebP output 📝 Subtitles Burn-in SRT/ASS/VTT subtitles Multiple styles available Customizable font size Works great with Whisper MCP

---

🚀 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

1. Open Dive Desktop
2. Click "+ Add MCP Server"
3. Paste the config provided above
4. 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 Parameters: file_path Returns: JSON with duration, resolution, codecs, bitrate, streams

🔄 Conversion & Compression

Tool	Description
ffmpeg_convert	Convert video/audio to different formats Parameters: file_path, output_format, scale, video_codec, audio_codec Formats: mp4, mkv, webm, mov, mp3, wav, etc.
ffmpeg_compress	Compress video to reduce file size Parameters: file_path, quality, scale, preset Quality: low, medium, high Preset: ultrafast to veryslow

✂️ Editing

Tool	Description
ffmpeg_trim	Trim video to extract a segment Parameters: file_path, start_time, end_time or duration Time format: "00:01:30" or seconds
ffmpeg_merge	Concatenate multiple videos into one Parameters: file_paths (list), output_path Supports: Same codec videos

🎵 Audio & Frames

Tool	Description
ffmpeg_extract_audio	Extract audio track from video Parameters: file_path, audio_format, bitrate Formats: mp3, aac, wav, flac, ogg, opus
ffmpeg_extract_frames	Extract frames as images Parameters: file_path, interval or count, format Formats: jpg, png, bmp, webp

📝 Subtitles

Tool	Description
ffmpeg_add_subtitles	Burn-in subtitles to video (hardcode) Parameters: file_path, subtitle_path, style, font_size, output_path Formats: SRT, ASS, VTT Styles: outline, shadow, background, glow

---

💡 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!

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