<div align="center">

<img src="assets/banner.png" alt="MCP-FFmpeg Banner" width="600" />

MCP-FFmpeg

FFmpeg video & audio editing tools via Model Context Protocol (MCP)

Give your AI assistant the power to edit video and audio — trim, transcode, overlay, compose, and more.

Quick Start · Tools · Configuration · Architecture

</div>

Why MCP-FFmpeg?

AI assistants are great at understanding what you want to do with media files, but they can't actually do it — until now. MCP-FFmpeg bridges the gap by exposing 30+ FFmpeg operations as MCP tools that any compatible AI assistant can call directly.

You: "Trim this video from 00:30 to 02:00, add a fade-in, and convert to 720p"
AI:  Calls trim_video → add_basic_transitions → set_video_resolution → Done!

Architecture

<div align="center"> <img src="assets/architecture.png" alt="MCP-FFmpeg Architecture" width="600" /> </div>

┌─────────────────────┐     MCP Protocol     ┌──────────────────────────┐
│   AI Assistants     │◄───────────────────►  │   mcp-ffmpeg Server      │
│                     │    JSON-RPC/stdio     │                          │
│  · Claude Code      │                       │  ┌────────┐ ┌────────┐  │
│  · Claude Desktop   │                       │  │ Video  │ │ Audio  │  │
│  · Cursor           │                       │  │ Tools  │ │ Tools  │  │
│  · Any MCP Client   │                       │  └────────┘ └────────┘  │
└─────────────────────┘                       │  ┌────────┐ ┌────────┐  │
                                              │  │Overlay │ │Compose │  │
                                              │  │ Tools  │ │ Tools  │  │
                                              │  └────────┘ └────────┘  │
                                              └──────────┬─────────────┘
                                                         │
                                                         ▼
                                              ┌──────────────────────┐
                                              │    FFmpeg Engine      │
                                              └──────────────────────┘

Quick Start

Prerequisites

Install & Run

git clone https://github.com/kevinten-ai/mcp-ffmpeg.git
cd mcp-ffmpeg
uv sync
uv run python main.py

MCP Client Configuration

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "ffmpeg-tools": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-ffmpeg", "run", "python", "main.py"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ffmpeg-tools": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-ffmpeg", "run", "python", "main.py"]
    }
  }
}

Cursor / Other MCP Clients

Use the same server configuration — any client that supports MCP's stdio transport will work.

Available Tools (30+)

Video Processing

Audio Processing

Video Audio Track

Overlays & Subtitles

Composition & Editing

System

Usage Examples

Basic Video Editing

"Trim intro.mp4 from 10s to 2:30 and save as intro_trimmed.mp4"
→ trim_video(video_path="intro.mp4", output_video_path="intro_trimmed.mp4",
             start_time="10", end_time="2:30")

Format Conversion

"Convert recording.mov to mp4 at 720p with h265 codec"
→ convert_video_properties(input_video_path="recording.mov",
                           output_video_path="recording.mp4",
                           target_format="mp4", resolution="720",
                           video_codec="libx265")

Adding Subtitles

"Burn subtitles.srt onto my video with large white text"
→ add_subtitles(video_path="video.mp4", srt_file_path="subtitles.srt",
                output_video_path="video_subtitled.mp4",
                font_style={"font_size": 28, "font_color": "&HFFFFFF"})

Video Composition

"Join clip1.mp4 and clip2.mp4 with a dissolve transition"
→ concatenate_videos(video_paths=["clip1.mp4", "clip2.mp4"],
                     output_video_path="final.mp4",
                     transition_effect="dissolve",
                     transition_duration=1.0)

Supported Transitions

The concatenate_videos tool supports 30+ xfade transitions for joining two videos:

Project Structure

mcp-ffmpeg/
├── main.py                          # Entry point
├── pyproject.toml                   # Project config & dependencies
├── src/ffmpeg_tools/
│   ├── __init__.py
│   ├── server.py                    # MCP server setup & tool registration
│   ├── utils.py                     # Shared utilities (probe, clip prep, etc.)
│   └── tools/
│       ├── audio.py                 # Audio processing tools (6 tools)
│       ├── video.py                 # Video & video-audio tools (13 tools)
│       ├── overlay.py               # Text/image/subtitle overlay tools (3 tools)
│       └── compose.py               # Concatenation, B-roll, transitions (4 tools)
├── tests/
│   ├── test_video_functions.py      # Test suite
│   └── sample_files/                # Test media files
└── assets/                          # Images for documentation

Testing

uv run pytest tests/ -v

Contributing

Contributions are welcome! Here are some ways to help:

• Add new FFmpeg tools (e.g., video stabilization, noise reduction)
• Improve error handling and validation
• Add more test coverage
• Improve documentation

License

MIT License — see LICENSE for details.

Acknowledgments

Based on video-audio-mcp by misbahsy.

<div align="center">

Built with [FastMCP](https://github.com/jlowin/fastmcp) and [FFmpeg](https://ffmpeg.org)

</div>