Video Audio Editing
STDIOFFmpeg-powered MCP server for professional video and audio editing operations.
FFmpeg-powered MCP server for professional video and audio editing operations.
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.
extract_audio_from_video - Extract audio tracks from video filestrim_video - Cut video segments with precise timingconvert_video_format - Convert between video formats (MP4, MOV, AVI, etc.)convert_video_properties - Comprehensive video property conversionchange_aspect_ratio - Adjust video aspect ratios with padding or croppingset_video_resolution - Change video resolution with quality preservationset_video_codec - Switch video codecs (H.264, H.265, VP9, etc.)set_video_bitrate - Adjust video quality and file sizeset_video_frame_rate - Change playback frame ratesconvert_audio_format - Convert between audio formats (MP3, WAV, AAC, etc.)convert_audio_properties - Comprehensive audio property conversionset_audio_bitrate - Adjust audio quality and compressionset_audio_sample_rate - Change audio sample ratesset_audio_channels - Convert between mono and stereoset_video_audio_track_codec - Change audio codec in video filesset_video_audio_track_bitrate - Adjust audio bitrate in videosset_video_audio_track_sample_rate - Change audio sample rate in videosset_video_audio_track_channels - Adjust audio channels in videosadd_subtitles - Burn subtitles with custom stylingadd_text_overlay - Add dynamic text overlays with timingadd_image_overlay - Insert watermarks and logosadd_b_roll - Insert B-roll footage with transitionsadd_basic_transitions - Apply fade in/out effectsconcatenate_videos - Join multiple videos with optional transitionschange_video_speed - Create slow-motion or time-lapse effectsremove_silence - Automatically remove silent segmentshealth_check - Verify server statusThe simplest way to get started is through the Smithery MCP registry:
# 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
# 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')"
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"] } } }
File → Preferences → Cursor Settings → MCPVideoAudioServercommanduv --directory /path/to/your/video-audio-mcp run server.pyAlternative configuration:
/path/to/python /path/to/video-audio-mcp/server.pyAdd to your MCP configuration:
{ "mcpServers": { "VideoAudioServer": { "command": "uv", "args": [ "--directory", "/path/to/your/video-audio-mcp", "run", "server.py" ], "env": {} } } }
The uv command is recommended because it:
For easier distribution, you can also run via npx if packaged:
{ "mcpServers": { "VideoAudioServer": { "command": "npx", "args": ["-y", "video-audio-mcp-server"] } } }
"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
"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
"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
# 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 )
# 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": "[email protected]" } ] )
# 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 )
The server includes comprehensive error handling:
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
python server.pyRun with debug logging:
python server.py --log-level DEBUG
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.
The test suite covers:
# Install test dependencies pip install pytest # Ensure FFmpeg is installed and accessible ffmpeg -version
# 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
# 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
The test suite automatically creates:
tests/test_outputs/ for generated files# 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)
$ 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 =========================
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
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
Some tests include performance validation:
💡 Tip: Run tests after any changes to ensure functionality remains intact. The comprehensive test suite catches most issues before they reach production.
We welcome contributions! Please see our Contributing Guide for details.
# 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/
This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ for the MCP community