🎬 Video & Audio Editing MCP Server

A comprehensive Model Context Protocol (MCP) server that provides powerful video and audio editing capabilities through FFmpeg. This server enables AI assistants to perform professional-grade video editing operations including format conversion, trimming, overlays, transitions, and advanced audio processing.

✨ Features

🎥 Video Processing: Format conversion, resolution scaling, codec changes, frame rate adjustment
🎵 Audio Processing: Format conversion, bitrate adjustment, sample rate changes, channel configuration
✂️ Editing Tools: Video trimming, speed adjustment, aspect ratio changes
🎨 Overlays & Effects: Text overlays, image watermarks, subtitle burning
🔗 Advanced Editing: Video concatenation with transitions, B-roll insertion, silence removal
🎭 Transitions: Fade in/out effects, crossfade transitions between clips

🛠️ Available Tools

Core Video Operations

extract_audio_from_video - Extract audio tracks from video files
trim_video - Cut video segments with precise timing
convert_video_format - Convert between video formats (MP4, MOV, AVI, etc.)
convert_video_properties - Comprehensive video property conversion
change_aspect_ratio - Adjust video aspect ratios with padding or cropping
set_video_resolution - Change video resolution with quality preservation
set_video_codec - Switch video codecs (H.264, H.265, VP9, etc.)
set_video_bitrate - Adjust video quality and file size
set_video_frame_rate - Change playback frame rates

Audio Processing

convert_audio_format - Convert between audio formats (MP3, WAV, AAC, etc.)
convert_audio_properties - Comprehensive audio property conversion
set_audio_bitrate - Adjust audio quality and compression
set_audio_sample_rate - Change audio sample rates
set_audio_channels - Convert between mono and stereo
set_video_audio_track_codec - Change audio codec in video files
set_video_audio_track_bitrate - Adjust audio bitrate in videos
set_video_audio_track_sample_rate - Change audio sample rate in videos
set_video_audio_track_channels - Adjust audio channels in videos

Creative Tools

add_subtitles - Burn subtitles with custom styling
add_text_overlay - Add dynamic text overlays with timing
add_image_overlay - Insert watermarks and logos
add_b_roll - Insert B-roll footage with transitions
add_basic_transitions - Apply fade in/out effects

Advanced Editing

concatenate_videos - Join multiple videos with optional transitions
change_video_speed - Create slow-motion or time-lapse effects
remove_silence - Automatically remove silent segments
health_check - Verify server status

🚀 Quick Start

Prerequisites (local installation)

Python 3.8+ - Download Python
FFmpeg - Install FFmpeg
uv (recommended) - Install uv or use pip

Installation

Option 1: Using Smithery (Easiest) ⭐

The simplest way to get started is through the Smithery MCP registry:

Clipboard-20250524-191433-493

Option 2: Using uv (Recommended for Development)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/misbahsy/video-audio-mcp.git
cd video-audio-mcp

# Install dependencies with uv
uv sync

# Verify FFmpeg installation
ffmpeg -version

Running the Server

# With uv (recommended)
uv run server.py

# Or with traditional python
python server.py

# Or with specific transport
python -c "from server import mcp; mcp.run(transport='stdio')"

🔧 Client Configuration

Claude Desktop (Recommended Configuration)

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/video-audio-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Alternative (using Python directly):

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "python",
      "args": ["/path/to/video-audio-mcp/server.py"]
    }
  }
}

Cursor IDE (Recommended Configuration)

Open Cursor Settings: File → Preferences → Cursor Settings → MCP
Click "Add New Server"
Configure:
- Name: VideoAudioServer
- Type: command
- Command: uv --directory /path/to/your/video-audio-mcp run server.py

Alternative configuration:

Command: /path/to/python /path/to/video-audio-mcp/server.py

Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/video-audio-mcp",
        "run",
        "server.py"
      ],
      "env": {}
    }
  }
}

Why Use uv?

The uv command is recommended because it:

Automatically manages dependencies without needing to activate virtual environments
Faster installation and dependency resolution
Better isolation - each project gets its own environment automatically
More reliable - handles Python version and dependency conflicts better
Modern tooling - the future of Python package management

Using NPX (Alternative)

For easier distribution, you can also run via npx if packaged:

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "npx",
      "args": ["-y", "video-audio-mcp-server"]
    }
  }
}

📖 Usage Examples

Basic Video Editing

"Can you convert this MP4 file to MOV format?"
→ Uses: convert_video_format

"Trim the video from 30 seconds to 2 minutes"
→ Uses: trim_video

"Extract the audio from this video as MP3"
→ Uses: extract_audio_from_video

Advanced Editing Workflows

"Create a highlight reel by concatenating these 3 clips with fade transitions"
→ Uses: concatenate_videos with transition effects

"Add my logo watermark to the top-right corner of this video"
→ Uses: add_image_overlay

"Remove all silent parts from this podcast recording"
→ Uses: remove_silence

"Add subtitles to this video with custom styling"
→ Uses: add_subtitles

Professional Workflows

"Convert this 4K video to 1080p, reduce bitrate to 2Mbps, and change to H.265 codec"
→ Uses: convert_video_properties

"Create a social media version: change to 9:16 aspect ratio, add text overlay, and compress"
→ Uses: change_aspect_ratio, add_text_overlay, set_video_bitrate

"Insert B-roll footage at 30 seconds with a fade transition"
→ Uses: add_b_roll

🎯 Real-World Use Cases

Content Creation

YouTube Videos: Automated editing, thumbnail generation, format optimization
Social Media: Aspect ratio conversion, text overlays, compression for platforms
Podcasts: Audio extraction, silence removal, format conversion

Professional Video Production

Corporate Videos: Logo watermarking, subtitle addition, quality standardization
Educational Content: Screen recording processing, chapter markers, accessibility features
Marketing Materials: B-roll integration, transition effects, brand consistency

Workflow Automation

Batch Processing: Convert entire video libraries to new formats
Quality Control: Standardize video properties across projects
Archive Management: Extract audio for transcription, create preview clips

🔍 Tool Reference

Video Format Conversion

# Convert MP4 to MOV with specific properties
convert_video_properties(
    input_video_path="input.mp4",
    output_video_path="output.mov",
    target_format="mov",
    resolution="1920x1080",
    video_codec="libx264",
    video_bitrate="5M",
    frame_rate=30
)

Text Overlays with Timing

# Add multiple text overlays with different timings
add_text_overlay(
    video_path="input.mp4",
    output_video_path="output.mp4",
    text_elements=[
        {
            "text": "Welcome to our presentation",
            "start_time": "0",
            "end_time": "3",
            "font_size": 48,
            "font_color": "white",
            "x_pos": "center",
            "y_pos": "center"
        },
        {
            "text": "Chapter 1: Introduction",
            "start_time": "5",
            "end_time": "8",
            "font_size": 36,
            "box": True,
            "box_color": "black@0.7"
        }
    ]
)

Advanced Concatenation

# Join videos with crossfade transition
concatenate_videos(
    video_paths=["clip1.mp4", "clip2.mp4"],
    output_video_path="final.mp4",
    transition_effect="dissolve",
    transition_duration=1.5
)

🛡️ Error Handling

The server includes comprehensive error handling:

File Validation: Checks for file existence before processing
Format Support: Validates supported formats and codecs
Graceful Fallbacks: Attempts codec copying before re-encoding
Detailed Logging: Provides clear error messages for troubleshooting

🔧 Troubleshooting

Common Issues

FFmpeg not found

# Install FFmpeg
# macOS: brew install ffmpeg
# Ubuntu: sudo apt install ffmpeg
# Windows: Download from https://ffmpeg.org/

Permission errors

# Ensure file permissions
chmod +x server.py

MCP server not connecting

Check file paths in configuration
Verify Python environment
Test server manually: python server.py
Check client logs for detailed errors

Debug Mode

Run with debug logging:

python server.py --log-level DEBUG

🧪 Testing

This project includes a comprehensive test suite that validates all video and audio editing functions. The tests ensure reliability and help catch regressions during development.

Test Coverage

The test suite covers:

✅ Core Functions: All 30+ video/audio editing tools
🎬 Video Operations: Format conversion, trimming, resolution changes, codec switching
🎵 Audio Processing: Bitrate adjustment, sample rate changes, channel configuration
🎨 Creative Tools: Text overlays, image watermarks, subtitle burning
🔗 Advanced Features: Video concatenation, B-roll insertion, transitions
⚡ Performance: Speed changes, silence removal, aspect ratio adjustments
🛡️ Error Handling: Invalid inputs, missing files, unsupported formats

Running Tests

Prerequisites for Testing

# Install test dependencies
pip install pytest

# Ensure FFmpeg is installed and accessible
ffmpeg -version

Basic Test Execution

# Run all tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run specific test file
pytest tests/test_video_functions.py

# Run specific test function
pytest tests/test_video_functions.py::test_extract_audio

Advanced Test Options

# Run tests with detailed output and no capture
pytest tests/ -v -s

# Run tests and stop on first failure
pytest tests/ -x

# Run tests with coverage report
pytest tests/ --cov=server

# Run only failed tests from last run
pytest tests/ --lf

Test Environment Setup

The test suite automatically creates:

Sample Files: Test videos, audio files, and images
Output Directory: tests/test_outputs/ for generated files
Temporary Files: B-roll clips and transition test materials

# Test files are created in:
tests/
├── test_outputs/          # Generated test results
├── sample_files/          # Auto-generated sample media
├── test_video_functions.py # Main test suite
└── sample.mp4            # Primary test video (if available)

Sample Test Output

$ pytest tests/test_video_functions.py -v

tests/test_video_functions.py::test_health_check PASSED
tests/test_video_functions.py::test_extract_audio PASSED
tests/test_video_functions.py::test_trim_video PASSED
tests/test_video_functions.py::test_convert_audio_properties PASSED
tests/test_video_functions.py::test_convert_video_properties PASSED
tests/test_video_functions.py::test_add_text_overlay PASSED
tests/test_video_functions.py::test_add_subtitles PASSED
tests/test_video_functions.py::test_concatenate_videos PASSED
tests/test_video_functions.py::test_add_b_roll PASSED
tests/test_video_functions.py::test_add_basic_transitions PASSED
tests/test_video_functions.py::test_concatenate_videos_with_xfade PASSED

========================= 25 passed in 45.2s =========================

Test Categories

🎯 Core Functionality Tests

Video format conversion and property changes
Audio extraction and processing
File trimming and basic operations

🎨 Creative Feature Tests

Text overlay positioning and timing
Image watermark placement and opacity
Subtitle burning with custom styling

🔗 Advanced Editing Tests

Multi-video concatenation with transitions
B-roll insertion with various positions
Speed changes and silence removal

🛡️ Error Handling Tests

Invalid file paths and missing files
Unsupported formats and codecs
Edge cases and boundary conditions

Writing Custom Tests

To add new tests for additional functionality:

def test_new_feature():
    """Test description"""
    # Setup
    input_file = "path/to/test/file.mp4"
    output_file = os.path.join(OUTPUT_DIR, "test_output.mp4")
    
    # Execute
    result = your_new_function(input_file, output_file, parameters)
    
    # Validate
    assert "success" in result.lower()
    assert os.path.exists(output_file)
    
    # Optional: Validate output properties
    duration = get_media_duration(output_file)
    assert duration > 0

Continuous Integration

The test suite is designed to work in CI/CD environments:

# Example GitHub Actions workflow
- name: Install FFmpeg
  run: sudo apt-get install ffmpeg

- name: Install dependencies
  run: pip install -r requirements.txt pytest

- name: Run tests
  run: pytest tests/ -v

Performance Testing

Some tests include performance validation:

Duration Checks: Verify output video lengths match expectations
Quality Validation: Ensure format conversions maintain quality
File Size Monitoring: Check compression and bitrate changes

Test Data Management

Automatic Cleanup: Tests clean up temporary files
Sample Generation: Creates test media files as needed
Deterministic Results: Tests produce consistent, reproducible results

💡 Tip: Run tests after any changes to ensure functionality remains intact. The comprehensive test suite catches most issues before they reach production.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone and setup development environment
git clone https://github.com/misbahsy/video-audio-mcp.git
cd video-audio-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

📄 License

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

🙏 Acknowledgments

Built with FastMCP framework
Powered by FFmpeg for media processing
Inspired by the Model Context Protocol specification

📞 Support

🐛 Bug Reports: GitHub Issues

Made with ❤️ for the MCP community