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

Getting Started

Add the following config to your MCP client:

MCP Client Configuration

1. Open Dive Desktop

2. Click "+ Add MCP Server"

3. Paste the config provided above

4. Click "Save" and you're ready!

Use the Claude Code CLI to add the ffmpeg MCP server:

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

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.

Install via the VS Code CLI:

Follow the configure MCP guide using the standard config from above.

Manual Installation

Or with uv:

🛠️ Available Tools

All tools are prefixed with ffmpeg_ to avoid naming conflicts with other MCP servers.

📊 Media Information

Get comprehensive video/audio metadata

• Parameters: file_path

• Returns: JSON with duration, resolution, codecs, bitrate, streams

🔄 Conversion & Compression

Convert video/audio to different formats

• Parameters: file_path, output_format, scale, video_codec, audio_codec

• Formats: mp4, mkv, webm, mov, mp3, wav, etc.

Compress video to reduce file size

• Parameters: file_path, quality, scale, preset

• Quality: low, medium, high

• Preset: ultrafast to veryslow

✂️ Editing

Trim video to extract a segment

• Parameters: file_path, start_time, end_time or duration

• Time format: "00:01:30" or seconds

Concatenate multiple videos into one

• Parameters: file_paths (list), output_path

• Supports: Same codec videos

🎵 Audio & Frames

Extract audio track from video

• Parameters: file_path, audio_format, bitrate

• Formats: mp3, aac, wav, flac, ogg, opus

Extract frames as images

• Parameters: file_path, interval or count, format

• Formats: jpg, png, bmp

📝 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

Convert Videos

Compress Videos

Trim Videos

Extract Audio

Extract Frames

Merge Videos

Add Subtitles

🔧 Configuration

Environment Variables

Custom Configuration

🏗️ 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

📝 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