# FFmpeg MCP Server

Model Context Protocol (MCP) server that provides **40+ advanced FFmpeg tools** for video/audio processing, analysis, and streaming

## Features

### Media Analysis & Probing (7 tools)
- **get_media_info** — Comprehensive metadata (codecs, bitrates, resolution, fps, etc.)
- **get_video_resolution** — Width, height, aspect ratio
- **get_duration** — File duration in seconds & formatted
- **list_streams** — All video, audio, subtitle streams
- **get_frame_count** — Total frame count
- **detect_scene_changes** — Scene cut detection with timestamps
- **get_keyframes** — Keyframe timestamp listing

### Format Conversion (5 tools)
- **convert_video** — Full codec/quality control (x264, x265, VP9, AV1, etc.)
- **convert_audio** — Audio format conversion (MP3, AAC, FLAC, WAV, OGG, etc.)
- **convert_to_gif** — High-quality GIF with palette optimization
- **batch_convert** — Bulk convert entire directories
- **extract_audio** — Extract audio track from video

### Video Editing (10 tools)
- **trim_video** — Cut segments by time
- **merge_videos** — Concatenate multiple videos
- **resize_video** — Scale to any resolution
- **change_speed** — Speed up / slow down with audio sync
- **extract_frames** — Export frames as images
- **create_video_from_images** — Image sequence → video
- **rotate_video** — 90°, 180°, 270° or arbitrary angle
- **crop_video** — Crop a region
- **generate_thumbnail** — Extract frame as image
- **add_thumbnail** — Embed poster image in MP4

### Audio Processing (7 tools)
- **adjust_volume** — Volume control (factor, dB, percentage)
- **normalize_audio** — EBU R128 loudness normalization
- **mix_audio** — Overlay/replace audio tracks
- **remove_audio** — Strip all audio
- **add_fade_audio** — Fade in/out effects
- **generate_waveform** — Audio waveform visualization
- **generate_spectrogram** — Spectrogram image generation

### Visual Effects & Filters (7 tools)
- **add_text_overlay** — Text/watermark with position, timing, styling
- **add_image_overlay** — Logo/watermark image overlay
- **apply_video_filter** — Any FFmpeg filter (blur, sharpen, eq, hue, etc.)
- **add_fade** — Video fade in/out
- **picture_in_picture** — PiP effect with two videos
- **side_by_side** — Horizontal/vertical split view
- **create_slideshow** — Image slideshow with transitions (fade, wipe, slide)

### Subtitles (3 tools)
- **extract_subtitles** — Extract subtitle tracks (SRT, ASS, VTT)
- **burn_subtitles** — Hardcode subtitles into video
- **add_subtitle_track** — Add soft subtitles with language tags

### Streaming (4 tools)
- **create_hls_stream** — Generate HLS segments + playlist
- **create_dash_stream** — Generate DASH manifest + segments
- **create_adaptive_hls** — Multi-bitrate adaptive streaming (1080p/720p/480p/360p)
- **stream_to_rtmp** — Stream to YouTube Live, Twitch, etc.

### Advanced Processing (14 tools)
- **two_pass_encode** — Optimal bitrate distribution
- **stabilize_video** — Shake reduction (vidstab)
- **denoise_video** — Noise reduction (hqdn3d, nlmeans)
- **deinterlace_video** — Interlaced → progressive
- **change_framerate** — FPS conversion with motion interpolation
- **compress_video** — Target file size or CRF compression
- **add_metadata** — Add/modify tags (title, artist, year, etc.)
- **remove_metadata** — Strip all metadata
- **reverse_video** — Play video backwards
- **create_mosaic** — Video grid layout (2x2, 3x2, etc.)
- **run_custom_ffmpeg** — Execute any custom FFmpeg command
- **get_ffmpeg_version** — FFmpeg version info
- **list_supported_formats** — All supported formats
- **list_supported_codecs** — All supported codecs

## Prerequisites

- **Python 3.10+**
- **FFmpeg** installed and available on PATH
  - Windows: `winget install ffmpeg` or download from https://ffmpeg.org/download.html
  - macOS: `brew install ffmpeg`
  - Linux: `sudo apt install ffmpeg`

## Installation

```bash
cd ffmpeg-mcp
pip install -r requirements.txt
```

## Usage

### Manual Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "python",
      "args": ["C:/path/to/ffmpeg-mcp/server.py"]
    }
  }
}
```

## Project Structure

```
ffmpeg-mcp/
├── server.py           # MCP server entry point
├── utils.py            # Shared utilities (run_command, probe, validation)
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project metadata
├── README.md           # This file
└── tools/
    ├── __init__.py     # Tool registration
    ├── probe.py        # Media analysis & probing tools
    ├── convert.py      # Format conversion tools
    ├── video.py        # Video editing tools
    ├── audio.py        # Audio processing tools
    ├── effects.py      # Visual effects & filter tools
    ├── subtitles.py    # Subtitle management tools
    ├── streaming.py    # Streaming (HLS/DASH/RTMP) tools
    └── advanced.py     # Advanced processing tools
```

## Examples

### Analyze a video
> "Get detailed info about this video: C:/Videos/test.mp4"

### Convert video
> "Convert test.mp4 to MKV with H.265 codec at CRF 20 quality"

### Create GIF
> "Create a GIF from the video between 5s and 15s, 320px wide"

### Compress video
> "Compress this video to under 50MB"

### Adaptive streaming
> "Create an HLS stream with 1080p, 720p, and 480p quality levels"

### Stabilize shaky video
> "Stabilize this shaky video"

## License

MIT