Skip to content misbahsy video-audio-mcp Repository navigation Code Issues 2 (2) Pull requests 1 (1) Agents Actions Projects Security and quality Insights Owner avatar video-audio-mcp Public misbahsy/video-audio-mcp Go to file t T Name misbahsy misbahsy Update README.md 905549b · last year .cursor/rules license last year tests working mcp server last year .gitignore license last year CONTRIBUTING.md license last year LICENSE license last year README.md Update README.md last year favicon.svg icon last year icon.svg icon last year main.py working mcp server last year pyproject.toml working mcp server last year requirements.txt working mcp server last year server.py working mcp server last year uv.lock working mcp server last year Repository files navigation README Contributing MIT license Video & Audio Editing MCP Server 🎬 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.

License: MIT Python 3.8+ MCP Compatible smithery badge

✨ 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": "[email protected]" } ] ) 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

About An FFMPEG powered MCP server for basic Video and Audio editing

Resources Readme License MIT license Contributing Contributing Activity Stars 81 stars Watchers 2 watching Forks 14 forks Report repository Releases No releases published Deployments 7 production

• 6 deployments Packages No packages published Contributors 1 @misbahsy misbahsy Misbah Syed Languages Python 100.0% Footer © 2026 GitHub, Inc. Footer navigation Terms Privacy Security Status Community Docs Contact Manage cookies Do not share my personal information