📦

Ffmpeg MCP Lite

MCP server for video/audio processing via FFmpeg - convert, compress, trim, extract audio, add subtitles

0 installs

22 stars

2 forks

Trust: 64 — Good

Devtools

Installation

npx ffmpeg-mcp-lite

Ask AI about Ffmpeg MCP Lite

I know everything about Ffmpeg MCP Lite. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

🎬 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 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

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

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

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

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

⬆ Back to Top

Ffmpeg MCP Lite

Installation

Reviews

Documentation

🎬 ffmpeg-mcp

✨ Features

📊 Media Information

🔄 Format Conversion

🗜️ Video Compression

✂️ Video Trimming

🎵 Audio Extraction

🎞️ Advanced Features

📝 Subtitles

🚀 Installation

Prerequisites

Getting Started

MCP Client Configuration

Manual Installation

🛠️ Available Tools

📊 Media Information

🔄 Conversion & Compression

✂️ Editing

🎵 Audio & Frames

📝 Subtitles

💡 Usage Examples

Get Media Information

Convert Videos

Compress Videos

Trim Videos

Extract Audio

Extract Frames

Merge Videos

Add Subtitles

🔧 Configuration

Environment Variables

Custom Configuration

🏗️ Architecture

Built With

Key Features

🤝 Contributing

Development

📝 License

🙏 Acknowledgments

Security Checklist