video-audio-mcp
An FFMPEG powered MCP server for basic Video and Audio editing
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/misbahsy--video-audio-mcp)HTML
<a href="/listings/misbahsy--video-audio-mcp"><img src="/api/listings/misbahsy--video-audio-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Prerequisites (local installation)
1. **Python 3.8+** - [Download Python](https://www.python.org/downloads/) 2. **FFmpeg** - [Install FFmpeg](https://ffmpeg.org/download.html) 3. **uv** (recommended) - [Install uv](https://docs.astral.sh/uv/getting-started/installation/) or use pip
Installation
Option 1: Using Smithery (Easiest) ⭐
The simplest way to get started is through the [Smithery MCP registry](https://smithery.ai/server/@misbahsy/video-audio-mcp):
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')"
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 574 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <img src="icon.svg" alt="Video & Audio Editing MCP Server" width="128" height="128">
- </div>
- # 🎬 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.
- [](https://opensource.org/licenses/MIT)
- [](https://www.python.org/downloads/)
- [](https://modelcontextprotocol.io/)
- [](https://smithery.ai/server/@misbahsy/video-audio-mcp)
- ## ✨ 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)
- 1. **Python 3.8+** - [Download Python](https://www.python.org/downloads/)
- 2. **FFmpeg** - [Install FFmpeg](https://ffmpeg.org/download.html)
- 3. **uv** (recommended) - [Install uv](https://docs.astral.sh/uv/getting-started/installation/) or use pip
- ### Installation
- #### Option 1: Using Smithery (Easiest) ⭐
- The simplest way to get started is through the [Smithery MCP registry](https://smithery.ai/server/@misbahsy/video-audio-mcp):
- 
- #### Option 2: Using uv (Recommended for Development)
- ```bash
- # 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
- ```bash
- # 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`
- ```json
- {
- "mcpServers": {
- "VideoAudioServer": {
- "command": "uv",
- "args": [
- "--directory",
- "/path/to/your/video-audio-mcp",
- "run",
- "server.py"
- ]
- }
- }
- }
- ```
- **Alternative (using Python directly):**
- ```json
- {
- "mcpServers": {
- "VideoAudioServer": {
- "command": "python",
- "args": ["/path/to/video-audio-mcp/server.py"]
- }
- }
- }
- ```
- ### Cursor IDE (Recommended Configuration)
- 1. Open Cursor Settings: `File → Preferences → Cursor Settings → MCP`
- 2. Click "Add New Server"
- 3. 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:
- ```json
- {
- "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:
- ```json
- {
- "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
- ```python
- # 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
- ```python
- # 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
- ```python
- # 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**
- ```bash
- # Install FFmpeg
- # macOS: brew install ffmpeg
- # Ubuntu: sudo apt install ffmpeg
- # Windows: Download from https://ffmpeg.org/
- ```
- **Permission errors**
- ```bash
- # Ensure file permissions
- chmod +x server.py
- ```
- **MCP server not connecting**
- 1. Check file paths in configuration
- 2. Verify Python environment
- 3. Test server manually: `python server.py`
- 4. Check client logs for detailed errors
- ### Debug Mode
- Run with debug logging:
- ```bash
- 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
- ```bash
- # Install test dependencies
- pip install pytest
- # Ensure FFmpeg is installed and accessible
- ffmpeg -version
- ```
- #### Basic Test Execution
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- $ 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:
- ```python
- 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:
- ```yaml
- # 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](CONTRIBUTING.md) for details.
- ### Development Setup
- ```bash
- # 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](LICENSE) file for details.
- ## 🙏 Acknowledgments
- - Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
- - Powered by [FFmpeg](https://ffmpeg.org/) for media processing
- - Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/) specification
- ## 📞 Support
- - 🐛 **Bug Reports**: [GitHub Issues](https://github.com/misbahsy/video-audio-mcp/issues)
- ---
- **Made with ❤️ for the MCP community**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.