ofekfell/media-mcp-editor

🤖 Process Steps

Natural Language Request -> Editing Workflow Building -> Workflow Rendering

✨ Features

📊 Media Information & Analysis

• 📋 Media Info - Comprehensive file analysis (duration, resolution, codecs, format, bitrate)

🛠️ Quick Start

💻 Local Installation

# 📥 Clone the repository
git clone <repository-url>
cd media-mcp

# 📦 Install dependencies
pip install -e .

# 🛠️ Install FFmpeg
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Windows - Download from https://ffmpeg.org/download.html

🚀 Usage

🔗 Connect to LLM Clients

This MCP server can be integrated with various LLM clients that support the Model Context Protocol:

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "media-mcp": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/media-mcp-editor",
        "run",
        "server.py"
      ]
    }
  }
}

Other MCP-Compatible Clients

• Connection: Use stdio transport with the server command
• Protocol: Model Context Protocol (MCP)
• Tools Available: All media processing operations listed below

🎯 API Operations

📊 Media Information

🎬 Basic Video Operations

🎵 Audio Operations

🔗 Advanced Operations

💡 Using Examples

Showcasing MCP's natural language interface that generates JSON workflows

🎬 Simple Video Editing

🗣️ User: "I need to trim the first 30 seconds from my video"

🤖 Generated Workflow for Rendering:

{
  "action": "trim",
  "params": {"start": 0, "duration": 30},
  "input": {"url": "input_video.mp4"}
}

🎞️ Multi-Video Projects

🗣️ User: "Combine my intro, main content, and outro videos into one file"

🤖 Generated Workflow for Rendering:

{
  "action": "concat",
  "input": [
    {"url": "intro.mp4"},
    {"url": "main_content.mp4"},
    {"url": "outro.mp4"}
  ]
}

🔧 Complex Workflow

🗣️ User: "Scale my video to 1080p, add a 2-second fade-in at the beginning, then trim it to 15 seconds starting from the 5-second mark"

🤖 Generated Workflow for Rendering:

{
  "action": "trim",
  "params": {"start": 5, "duration": 15},
  "input": {
    "action": "fade",
    "params": {"fade_type": "in", "start_time": 0, "duration": 2},
    "input": {
      "action": "scale",
      "params": {"width": 1920, "height": 1080},
      "input": {"url": "https://example.com/video.mp4"}
    }
  }
}

🎭 Picture-in-Picture

🗣️ User: "Add a small overlay video in the top-right corner of my main video"

🤖 Generated Workflow for Rendering:

{
  "action": "overlay",
  "params": {"x": 50, "y": 50},
  "input": [
    {"url": "main_video.mp4"},
    {"url": "overlay_video.mp4"}
  ]
}

🌅 Professional Transitions

🗣️ User: "Create a smooth 2-second crossfade transition between two 10-second video clips"

🤖 Generated Workflow for Rendering:

{
  "action": "crossfade",
  "params": {
    "duration": 2.0,
    "stream1_duration": 10.0,
    "transition": "fade"
  },
  "input": [
    {"url": "video1.mp4"},
    {"url": "video2.mp4"}
  ]
}

🎵 Audio Processing

🗣️ User: "Make the audio 50% louder and change the sample rate to 48kHz"

🤖 Generated Workflow for Rendering:

{
  "action": "audio_resample",
  "params": {"sample_rate": 48000},
  "input": {
    "action": "change_volume",
    "params": {"volume": 1.5},
    "input": {"url": "audio_file.mp3"}
  }
}

🧪 Testing

Comprehensive test suite with 38 passing tests!

# 🧪 Run all tests
python -m pytest tests/ -v

# 🎯 Run specific test file
python -m pytest tests/test_media_mcp_handler.py -v

# 📊 Run with coverage
python -m pytest tests/ --cov=media_mcp_handler --cov=ffmpeg_utils

📈 Test Coverage

• ✅ 38 Tests Passing
• 🎬 Media Operations - All video/audio functions
• 🔧 Workflow Processing - Complex pipeline testing
• 🌐 URL Handling - Remote file processing
• 📁 File Management - Local file operations
• ⚠️ Error Handling - Comprehensive error scenarios

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

• 🐛 Found a bug? Open an issue
• 💡 Have a feature request? Start a discussion
• 📧 Need help? Check our documentation