🎬 ffmpeg-mcp

<div align="center">

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

</div>

---

✨ Features

<table> <tr> <td width="50%">

📊 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

</td> <td width="50%">

🎵 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

</td> </tr> </table>

---

🚀 Installation

Prerequisites

Install FFmpeg on your system:

<table> <tr> <th>Platform</th> <th>Command</th> </tr> <tr> <td>🪟 <strong>Windows</strong></td> <td><code>winget install FFmpeg</code></td> </tr> <tr> <td>🍎 <strong>macOS</strong></td> <td><code>brew install ffmpeg</code></td> </tr> <tr> <td>🐧 <strong>Linux</strong></td> <td><code>sudo apt install ffmpeg</code></td> </tr> </table>

Getting Started

Add the following config to your MCP client:

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

MCP Client Configuration

<details open> <summary><strong>Dive</strong></summary>

1. Open Dive Desktop
2. Click "+ Add MCP Server"
3. Paste the config provided above
4. Click "Save" and you're ready!

</details>

<details> <summary><strong>Claude Code</strong></summary>

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

claude mcp add ffmpeg uvx ffmpeg-mcp-lite

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

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"]
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

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

</details>

<details> <summary><strong>VS Code / Copilot</strong></summary>

Install via the VS Code CLI:

code --add-mcp '{"name":"ffmpeg","command":"uvx","args":["ffmpeg-mcp-lite"]}'

</details>

<details> <summary><strong>Windsurf</strong></summary>

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

</details>

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

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ffmpeg_get_info</code></td> <td>

Get comprehensive video/audio metadata

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

</td> </tr> </table>

🔄 Conversion & Compression

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ffmpeg_convert</code></td> <td>

Convert video/audio to different formats

• Parameters: file_path, output_format, scale, video_codec, audio_codec
• Formats: mp4, mkv, webm, mov, mp3, wav, etc.

</td> </tr> <tr> <td><code>ffmpeg_compress</code></td> <td>

Compress video to reduce file size

• Parameters: file_path, quality, scale, preset
• Quality: low, medium, high
• Preset: ultrafast to veryslow

</td> </tr> </table>

✂️ Editing

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ffmpeg_trim</code></td> <td>

Trim video to extract a segment

• Parameters: file_path, start_time, end_time or duration
• Time format: "00:01:30" or seconds

</td> </tr> <tr> <td><code>ffmpeg_merge</code></td> <td>

Concatenate multiple videos into one

• Parameters: file_paths (list), output_path
• Supports: Same codec videos

</td> </tr> </table>

🎵 Audio & Frames

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ffmpeg_extract_audio</code></td> <td>

Extract audio track from video

• Parameters: file_path, audio_format, bitrate
• Formats: mp3, aac, wav, flac, ogg, opus

</td> </tr> <tr> <td><code>ffmpeg_extract_frames</code></td> <td>

Extract frames as images

• Parameters: file_path, interval or count, format
• Formats: jpg, png, bmp

</td> </tr> </table>

📝 Subtitles

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ffmpeg_add_subtitles</code></td> <td>

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

</td> </tr> </table>

---

💡 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

---

<div align="center">

⬆ Back to Top

</div>