{"id":29114937,"url":"https://github.com/misbahsy/video-audio-mcp","last_synced_at":"2025-09-15T23:56:11.126Z","repository":{"id":295295434,"uuid":"989722529","full_name":"misbahsy/video-audio-mcp","owner":"misbahsy","description":"An FFMPEG powered MCP server for basic Video and Audio editing","archived":false,"fork":false,"pushed_at":"2025-05-24T19:15:22.000Z","size":13583,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T11:11:36.900Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/misbahsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-24T17:31:55.000Z","updated_at":"2025-06-26T09:48:52.000Z","dependencies_parsed_at":"2025-05-24T18:49:13.095Z","dependency_job_id":null,"html_url":"https://github.com/misbahsy/video-audio-mcp","commit_stats":null,"previous_names":["misbahsy/video-audio-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/misbahsy/video-audio-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misbahsy%2Fvideo-audio-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misbahsy%2Fvideo-audio-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misbahsy%2Fvideo-audio-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misbahsy%2Fvideo-audio-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/misbahsy","download_url":"https://codeload.github.com/misbahsy/video-audio-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misbahsy%2Fvideo-audio-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275338801,"owners_count":25447036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-29T11:06:48.222Z","updated_at":"2025-09-15T23:56:11.117Z","avatar_url":"https://github.com/misbahsy.png","language":"Python","funding_links":[],"categories":["MCP Servers for Creative Work","Other Tools and Integrations"],"sub_categories":["Image, Video, Audio Generation","How to Submit"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"icon.svg\" alt=\"Video \u0026 Audio Editing MCP Server\" width=\"128\" height=\"128\"\u003e\n\u003c/div\u003e\n\n# 🎬 Video \u0026 Audio Editing MCP Server\n\nA 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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)\n[![smithery badge](https://smithery.ai/badge/@misbahsy/video-audio-mcp)](https://smithery.ai/server/@misbahsy/video-audio-mcp)\n\n## ✨ Features\n\n- **🎥 Video Processing**: Format conversion, resolution scaling, codec changes, frame rate adjustment\n- **🎵 Audio Processing**: Format conversion, bitrate adjustment, sample rate changes, channel configuration\n- **✂️ Editing Tools**: Video trimming, speed adjustment, aspect ratio changes\n- **🎨 Overlays \u0026 Effects**: Text overlays, image watermarks, subtitle burning\n- **🔗 Advanced Editing**: Video concatenation with transitions, B-roll insertion, silence removal\n- **🎭 Transitions**: Fade in/out effects, crossfade transitions between clips\n\n## 🛠️ Available Tools\n\n### Core Video Operations\n- `extract_audio_from_video` - Extract audio tracks from video files\n- `trim_video` - Cut video segments with precise timing\n- `convert_video_format` - Convert between video formats (MP4, MOV, AVI, etc.)\n- `convert_video_properties` - Comprehensive video property conversion\n- `change_aspect_ratio` - Adjust video aspect ratios with padding or cropping\n- `set_video_resolution` - Change video resolution with quality preservation\n- `set_video_codec` - Switch video codecs (H.264, H.265, VP9, etc.)\n- `set_video_bitrate` - Adjust video quality and file size\n- `set_video_frame_rate` - Change playback frame rates\n\n### Audio Processing\n- `convert_audio_format` - Convert between audio formats (MP3, WAV, AAC, etc.)\n- `convert_audio_properties` - Comprehensive audio property conversion\n- `set_audio_bitrate` - Adjust audio quality and compression\n- `set_audio_sample_rate` - Change audio sample rates\n- `set_audio_channels` - Convert between mono and stereo\n- `set_video_audio_track_codec` - Change audio codec in video files\n- `set_video_audio_track_bitrate` - Adjust audio bitrate in videos\n- `set_video_audio_track_sample_rate` - Change audio sample rate in videos\n- `set_video_audio_track_channels` - Adjust audio channels in videos\n\n### Creative Tools\n- `add_subtitles` - Burn subtitles with custom styling\n- `add_text_overlay` - Add dynamic text overlays with timing\n- `add_image_overlay` - Insert watermarks and logos\n- `add_b_roll` - Insert B-roll footage with transitions\n- `add_basic_transitions` - Apply fade in/out effects\n\n### Advanced Editing\n- `concatenate_videos` - Join multiple videos with optional transitions\n- `change_video_speed` - Create slow-motion or time-lapse effects\n- `remove_silence` - Automatically remove silent segments\n- `health_check` - Verify server status\n\n## 🚀 Quick Start\n\n### Prerequisites (local installation)\n\n1. **Python 3.8+** - [Download Python](https://www.python.org/downloads/)\n2. **FFmpeg** - [Install FFmpeg](https://ffmpeg.org/download.html)\n3. **uv** (recommended) - [Install uv](https://docs.astral.sh/uv/getting-started/installation/) or use pip\n\n### Installation\n\n#### Option 1: Using Smithery (Easiest) ⭐\n\nThe simplest way to get started is through the [Smithery MCP registry](https://smithery.ai/server/@misbahsy/video-audio-mcp):\n\n![Clipboard-20250524-191433-493](https://github.com/user-attachments/assets/68b9d98c-6e3e-48fe-9337-d16f8e82e0d6)\n\n\n#### Option 2: Using uv (Recommended for Development)\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/misbahsy/video-audio-mcp.git\ncd video-audio-mcp\n\n# Install dependencies with uv\nuv sync\n\n# Verify FFmpeg installation\nffmpeg -version\n```\n\n\n### Running the Server\n\n```bash\n# With uv (recommended)\nuv run server.py\n\n# Or with traditional python\npython server.py\n\n# Or with specific transport\npython -c \"from server import mcp; mcp.run(transport='stdio')\"\n```\n\n## 🔧 Client Configuration\n\n### Claude Desktop (Recommended Configuration)\n\nAdd to your `claude_desktop_config.json`:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"VideoAudioServer\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/your/video-audio-mcp\",\n        \"run\",\n        \"server.py\"\n      ]\n    }\n  }\n}\n```\n\n**Alternative (using Python directly):**\n```json\n{\n  \"mcpServers\": {\n    \"VideoAudioServer\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/video-audio-mcp/server.py\"]\n    }\n  }\n}\n```\n\n### Cursor IDE (Recommended Configuration)\n\n1. Open Cursor Settings: `File → Preferences → Cursor Settings → MCP`\n2. Click \"Add New Server\"\n3. Configure:\n   - **Name**: `VideoAudioServer`\n   - **Type**: `command`\n   - **Command**: `uv --directory /path/to/your/video-audio-mcp run server.py`\n\n**Alternative configuration:**\n   - **Command**: `/path/to/python /path/to/video-audio-mcp/server.py`\n\n### Windsurf\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"VideoAudioServer\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/your/video-audio-mcp\",\n        \"run\",\n        \"server.py\"\n      ],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### Why Use uv?\n\nThe `uv` command is recommended because it:\n- **Automatically manages dependencies** without needing to activate virtual environments\n- **Faster installation** and dependency resolution\n- **Better isolation** - each project gets its own environment automatically\n- **More reliable** - handles Python version and dependency conflicts better\n- **Modern tooling** - the future of Python package management\n\n### Using NPX (Alternative)\n\nFor easier distribution, you can also run via npx if packaged:\n\n```json\n{\n  \"mcpServers\": {\n    \"VideoAudioServer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"video-audio-mcp-server\"]\n    }\n  }\n}\n```\n\n## 📖 Usage Examples\n\n### Basic Video Editing\n\n```\n\"Can you convert this MP4 file to MOV format?\"\n→ Uses: convert_video_format\n\n\"Trim the video from 30 seconds to 2 minutes\"\n→ Uses: trim_video\n\n\"Extract the audio from this video as MP3\"\n→ Uses: extract_audio_from_video\n```\n\n### Advanced Editing Workflows\n\n```\n\"Create a highlight reel by concatenating these 3 clips with fade transitions\"\n→ Uses: concatenate_videos with transition effects\n\n\"Add my logo watermark to the top-right corner of this video\"\n→ Uses: add_image_overlay\n\n\"Remove all silent parts from this podcast recording\"\n→ Uses: remove_silence\n\n\"Add subtitles to this video with custom styling\"\n→ Uses: add_subtitles\n```\n\n### Professional Workflows\n\n```\n\"Convert this 4K video to 1080p, reduce bitrate to 2Mbps, and change to H.265 codec\"\n→ Uses: convert_video_properties\n\n\"Create a social media version: change to 9:16 aspect ratio, add text overlay, and compress\"\n→ Uses: change_aspect_ratio, add_text_overlay, set_video_bitrate\n\n\"Insert B-roll footage at 30 seconds with a fade transition\"\n→ Uses: add_b_roll\n```\n\n## 🎯 Real-World Use Cases\n\n### Content Creation\n- **YouTube Videos**: Automated editing, thumbnail generation, format optimization\n- **Social Media**: Aspect ratio conversion, text overlays, compression for platforms\n- **Podcasts**: Audio extraction, silence removal, format conversion\n\n### Professional Video Production\n- **Corporate Videos**: Logo watermarking, subtitle addition, quality standardization\n- **Educational Content**: Screen recording processing, chapter markers, accessibility features\n- **Marketing Materials**: B-roll integration, transition effects, brand consistency\n\n### Workflow Automation\n- **Batch Processing**: Convert entire video libraries to new formats\n- **Quality Control**: Standardize video properties across projects\n- **Archive Management**: Extract audio for transcription, create preview clips\n\n## 🔍 Tool Reference\n\n### Video Format Conversion\n\n```python\n# Convert MP4 to MOV with specific properties\nconvert_video_properties(\n    input_video_path=\"input.mp4\",\n    output_video_path=\"output.mov\",\n    target_format=\"mov\",\n    resolution=\"1920x1080\",\n    video_codec=\"libx264\",\n    video_bitrate=\"5M\",\n    frame_rate=30\n)\n```\n\n### Text Overlays with Timing\n\n```python\n# Add multiple text overlays with different timings\nadd_text_overlay(\n    video_path=\"input.mp4\",\n    output_video_path=\"output.mp4\",\n    text_elements=[\n        {\n            \"text\": \"Welcome to our presentation\",\n            \"start_time\": \"0\",\n            \"end_time\": \"3\",\n            \"font_size\": 48,\n            \"font_color\": \"white\",\n            \"x_pos\": \"center\",\n            \"y_pos\": \"center\"\n        },\n        {\n            \"text\": \"Chapter 1: Introduction\",\n            \"start_time\": \"5\",\n            \"end_time\": \"8\",\n            \"font_size\": 36,\n            \"box\": True,\n            \"box_color\": \"black@0.7\"\n        }\n    ]\n)\n```\n\n### Advanced Concatenation\n\n```python\n# Join videos with crossfade transition\nconcatenate_videos(\n    video_paths=[\"clip1.mp4\", \"clip2.mp4\"],\n    output_video_path=\"final.mp4\",\n    transition_effect=\"dissolve\",\n    transition_duration=1.5\n)\n```\n\n## 🛡️ Error Handling\n\nThe server includes comprehensive error handling:\n\n- **File Validation**: Checks for file existence before processing\n- **Format Support**: Validates supported formats and codecs\n- **Graceful Fallbacks**: Attempts codec copying before re-encoding\n- **Detailed Logging**: Provides clear error messages for troubleshooting\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**FFmpeg not found**\n```bash\n# Install FFmpeg\n# macOS: brew install ffmpeg\n# Ubuntu: sudo apt install ffmpeg\n# Windows: Download from https://ffmpeg.org/\n```\n\n**Permission errors**\n```bash\n# Ensure file permissions\nchmod +x server.py\n```\n\n**MCP server not connecting**\n1. Check file paths in configuration\n2. Verify Python environment\n3. Test server manually: `python server.py`\n4. Check client logs for detailed errors\n\n### Debug Mode\n\nRun with debug logging:\n```bash\npython server.py --log-level DEBUG\n```\n\n## 🧪 Testing\n\nThis project includes a comprehensive test suite that validates all video and audio editing functions. The tests ensure reliability and help catch regressions during development.\n\n### Test Coverage\n\nThe test suite covers:\n\n- **✅ Core Functions**: All 30+ video/audio editing tools\n- **🎬 Video Operations**: Format conversion, trimming, resolution changes, codec switching\n- **🎵 Audio Processing**: Bitrate adjustment, sample rate changes, channel configuration\n- **🎨 Creative Tools**: Text overlays, image watermarks, subtitle burning\n- **🔗 Advanced Features**: Video concatenation, B-roll insertion, transitions\n- **⚡ Performance**: Speed changes, silence removal, aspect ratio adjustments\n- **🛡️ Error Handling**: Invalid inputs, missing files, unsupported formats\n\n### Running Tests\n\n#### Prerequisites for Testing\n\n```bash\n# Install test dependencies\npip install pytest\n\n# Ensure FFmpeg is installed and accessible\nffmpeg -version\n```\n\n#### Basic Test Execution\n\n```bash\n# Run all tests\npytest tests/\n\n# Run with verbose output\npytest tests/ -v\n\n# Run specific test file\npytest tests/test_video_functions.py\n\n# Run specific test function\npytest tests/test_video_functions.py::test_extract_audio\n```\n\n#### Advanced Test Options\n\n```bash\n# Run tests with detailed output and no capture\npytest tests/ -v -s\n\n# Run tests and stop on first failure\npytest tests/ -x\n\n# Run tests with coverage report\npytest tests/ --cov=server\n\n# Run only failed tests from last run\npytest tests/ --lf\n```\n\n### Test Environment Setup\n\nThe test suite automatically creates:\n\n- **Sample Files**: Test videos, audio files, and images\n- **Output Directory**: `tests/test_outputs/` for generated files\n- **Temporary Files**: B-roll clips and transition test materials\n\n```bash\n# Test files are created in:\ntests/\n├── test_outputs/          # Generated test results\n├── sample_files/          # Auto-generated sample media\n├── test_video_functions.py # Main test suite\n└── sample.mp4            # Primary test video (if available)\n```\n\n### Sample Test Output\n\n```bash\n$ pytest tests/test_video_functions.py -v\n\ntests/test_video_functions.py::test_health_check PASSED\ntests/test_video_functions.py::test_extract_audio PASSED\ntests/test_video_functions.py::test_trim_video PASSED\ntests/test_video_functions.py::test_convert_audio_properties PASSED\ntests/test_video_functions.py::test_convert_video_properties PASSED\ntests/test_video_functions.py::test_add_text_overlay PASSED\ntests/test_video_functions.py::test_add_subtitles PASSED\ntests/test_video_functions.py::test_concatenate_videos PASSED\ntests/test_video_functions.py::test_add_b_roll PASSED\ntests/test_video_functions.py::test_add_basic_transitions PASSED\ntests/test_video_functions.py::test_concatenate_videos_with_xfade PASSED\n\n========================= 25 passed in 45.2s =========================\n```\n\n### Test Categories\n\n#### 🎯 **Core Functionality Tests**\n- Video format conversion and property changes\n- Audio extraction and processing\n- File trimming and basic operations\n\n#### 🎨 **Creative Feature Tests**\n- Text overlay positioning and timing\n- Image watermark placement and opacity\n- Subtitle burning with custom styling\n\n#### 🔗 **Advanced Editing Tests**\n- Multi-video concatenation with transitions\n- B-roll insertion with various positions\n- Speed changes and silence removal\n\n#### 🛡️ **Error Handling Tests**\n- Invalid file paths and missing files\n- Unsupported formats and codecs\n- Edge cases and boundary conditions\n\n### Writing Custom Tests\n\nTo add new tests for additional functionality:\n\n```python\ndef test_new_feature():\n    \"\"\"Test description\"\"\"\n    # Setup\n    input_file = \"path/to/test/file.mp4\"\n    output_file = os.path.join(OUTPUT_DIR, \"test_output.mp4\")\n    \n    # Execute\n    result = your_new_function(input_file, output_file, parameters)\n    \n    # Validate\n    assert \"success\" in result.lower()\n    assert os.path.exists(output_file)\n    \n    # Optional: Validate output properties\n    duration = get_media_duration(output_file)\n    assert duration \u003e 0\n```\n\n### Continuous Integration\n\nThe test suite is designed to work in CI/CD environments:\n\n```yaml\n# Example GitHub Actions workflow\n- name: Install FFmpeg\n  run: sudo apt-get install ffmpeg\n\n- name: Install dependencies\n  run: pip install -r requirements.txt pytest\n\n- name: Run tests\n  run: pytest tests/ -v\n```\n\n### Performance Testing\n\nSome tests include performance validation:\n\n- **Duration Checks**: Verify output video lengths match expectations\n- **Quality Validation**: Ensure format conversions maintain quality\n- **File Size Monitoring**: Check compression and bitrate changes\n\n### Test Data Management\n\n- **Automatic Cleanup**: Tests clean up temporary files\n- **Sample Generation**: Creates test media files as needed\n- **Deterministic Results**: Tests produce consistent, reproducible results\n\n\u003e **💡 Tip**: Run tests after any changes to ensure functionality remains intact. The comprehensive test suite catches most issues before they reach production.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/misbahsy/video-audio-mcp.git\ncd video-audio-mcp\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run tests\npytest tests/\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework\n- Powered by [FFmpeg](https://ffmpeg.org/) for media processing\n- Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/) specification\n\n## 📞 Support\n\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/misbahsy/video-audio-mcp/issues)\n\n\n---\n\n**Made with ❤️ for the MCP community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisbahsy%2Fvideo-audio-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmisbahsy%2Fvideo-audio-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisbahsy%2Fvideo-audio-mcp/lists"}