๐ฌ 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 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 rates
Audio Processing
convert_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 videos
Creative Tools
add_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 effects
Advanced Editing
concatenate_videos
- Join multiple videos with optional transitionschange_video_speed
- Create slow-motion or time-lapse effectsremove_silence
- Automatically remove silent segmentshealth_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:
Option 2: Using uv (Recommended for Development)
Running the Server
๐ง 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
Alternative (using Python directly):
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:
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:
๐ Usage Examples
Basic Video Editing
Advanced Editing Workflows
Professional Workflows
๐ฏ 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
Text Overlays with Timing
Advanced Concatenation
๐ก๏ธ 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
Permission errors
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:
๐งช 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
Basic Test Execution
Advanced Test Options
Test Environment Setup
The test suite automatically creates:
Sample Files: Test videos, audio files, and images
Output Directory:
tests/test_outputs/
for generated filesTemporary Files: B-roll clips and transition test materials
Sample Test Output
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:
Continuous Integration
The test suite is designed to work in CI/CD environments:
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
๐ 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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Provides powerful video and audio editing capabilities through FFmpeg, enabling AI assistants to perform professional-grade operations including format conversion, trimming, overlays, transitions, and advanced audio processing.
Related MCP Servers
- -securityFlicense-qualityEnables video editing using natural language commands powered by FFmpeg, supporting operations like trimming, merging, format conversion, and more with real-time progress tracking and error handling.Last updated -37
- AsecurityAlicenseAqualityA lightweight server that exposes FFmpeg's video processing capabilities to AI assistants through the Model Context Protocol (MCP), supporting operations like video format conversion, audio extraction, and adding watermarks.Last updated -84716MIT License
- AsecurityAlicenseAqualityAn MCP server providing video processing capabilities through FFmpeg, enabling dialog-based local video search, trimming, concatenation, and playback functionalities.Last updated -883MIT License
- -securityFlicense-qualityWeb-based video editing platform that provides direct editing functionality through a Model Context Protocol server, supporting media file management, timeline editing, and advanced transformation effects.Last updated -6