https://github.com/misbahsy/video-audio-mcp
An FFMPEG powered MCP server for basic Video and Audio editing
https://github.com/misbahsy/video-audio-mcp
Last synced: 28 days ago
JSON representation
An FFMPEG powered MCP server for basic Video and Audio editing
- Host: GitHub
- URL: https://github.com/misbahsy/video-audio-mcp
- Owner: misbahsy
- License: mit
- Created: 2025-05-24T17:31:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-05-24T19:15:22.000Z (5 months ago)
- Last Synced: 2025-06-29T11:11:36.900Z (4 months ago)
- Language: Python
- Size: 13 MB
- Stars: 13
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🎬 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**