FFmpeg MCP Proof of Concept

This project validates and demonstrates the capabilities of the ffmpeg-mcp Model Context Protocol (MCP) server.

Prerequisites

• Python: 3.10 or higher
• ffmpeg: System-wide installation
• uv: Python package manager

Install Prerequisites on macOS

# Install ffmpeg
brew install ffmpeg

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env

Project Structure

ffmpeg-mcp-poc/
├── README.md           # This file
├── assets/             # Test video files (generated)
├── ffmpeg-mcp/         # Cloned MCP server repository
├── output/             # Generated output files (created on run)
├── scripts/            # Helper scripts
│   └── generate_assets.sh
├── pyproject.toml      # Project dependencies
└── run_poc.py          # Main test script

Setup

1. Install ffmpeg-mcp dependencies:

   cd ffmpeg-mcp
   uv sync
   cd ..

2. Install PoC dependencies:

   uv sync

3. Generate test assets:

   ./scripts/generate_assets.sh

Running the PoC

Execute the test script:

uv run python run_poc.py

The script will:

1. Start the ffmpeg-mcp MCP server
2. Execute video operations:
   • get_video_info: Get metadata of source video
   • clip_video: Extract a 3-second clip
   • scale_video: Resize video to 320x240
   • overlay_video: Create picture-in-picture effect
   • concat_videos: Stitch two clips together
3. Validate output files are created

Expected Output

============================================================
  FFmpeg MCP Proof of Concept
============================================================

============================================================
  Checking Prerequisites
============================================================
[OK] Source A: /path/to/assets/source_a.mp4
[OK] Source B: /path/to/assets/source_b.mp4

============================================================
  Starting MCP Server
============================================================
...

============================================================
  Test Summary
============================================================
  [PASS] clip_test.mp4
  [PASS] scaled_test.mp4
  [PASS] overlay_test.mp4
  [PASS] concat_test.mp4

Results: 4 passed, 0 failed

*** All tests PASSED! ffmpeg-mcp is working correctly. ***

Claude Desktop / VSCode Configuration

To use ffmpeg-mcp with Claude Desktop or VSCode, add the following to your MCP settings:

{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ffmpeg-mcp-poc/ffmpeg-mcp",
        "run",
        "ffmpeg-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/ffmpeg-mcp-poc with the actual path to this project.

Available Tools

The ffmpeg-mcp server provides these tools:

Tool	Description
find_video_path	Recursively search for video files
get_video_info	Get video metadata (duration, fps, codec, etc.)
clip_video	Extract a segment from a video
scale_video	Resize video to specified dimensions
overlay_video	Create picture-in-picture effect
concat_videos	Stitch multiple videos together
play_video	Play video with ffplay
extract_frames_from_video	Extract frames as images

Troubleshooting

"uv: command not found"

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env

"ffmpeg: command not found"

Install ffmpeg:

brew install ffmpeg  # macOS

Test assets not found

Generate them:

./scripts/generate_assets.sh