Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/misbahsy--video-audio-mcp/badge.svg)](/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

i

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)

  1. <div align="center">
  2. <img src="icon.svg" alt="Video & Audio Editing MCP Server" width="128" height="128">
  3. </div>
  4. # 🎬 Video & Audio Editing MCP Server
  5. 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.
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
  8. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
  9. [![smithery badge](https://smithery.ai/badge/@misbahsy/video-audio-mcp)](https://smithery.ai/server/@misbahsy/video-audio-mcp)
  10. ## ✨ Features
  11. - **🎥 Video Processing**: Format conversion, resolution scaling, codec changes, frame rate adjustment
  12. - **🎵 Audio Processing**: Format conversion, bitrate adjustment, sample rate changes, channel configuration
  13. - **✂️ Editing Tools**: Video trimming, speed adjustment, aspect ratio changes
  14. - **🎨 Overlays & Effects**: Text overlays, image watermarks, subtitle burning
  15. - **🔗 Advanced Editing**: Video concatenation with transitions, B-roll insertion, silence removal
  16. - **🎭 Transitions**: Fade in/out effects, crossfade transitions between clips
  17. ## 🛠️ Available Tools
  18. ### Core Video Operations
  19. - `extract_audio_from_video` - Extract audio tracks from video files
  20. - `trim_video` - Cut video segments with precise timing
  21. - `convert_video_format` - Convert between video formats (MP4, MOV, AVI, etc.)
  22. - `convert_video_properties` - Comprehensive video property conversion
  23. - `change_aspect_ratio` - Adjust video aspect ratios with padding or cropping
  24. - `set_video_resolution` - Change video resolution with quality preservation
  25. - `set_video_codec` - Switch video codecs (H.264, H.265, VP9, etc.)
  26. - `set_video_bitrate` - Adjust video quality and file size
  27. - `set_video_frame_rate` - Change playback frame rates
  28. ### Audio Processing
  29. - `convert_audio_format` - Convert between audio formats (MP3, WAV, AAC, etc.)
  30. - `convert_audio_properties` - Comprehensive audio property conversion
  31. - `set_audio_bitrate` - Adjust audio quality and compression
  32. - `set_audio_sample_rate` - Change audio sample rates
  33. - `set_audio_channels` - Convert between mono and stereo
  34. - `set_video_audio_track_codec` - Change audio codec in video files
  35. - `set_video_audio_track_bitrate` - Adjust audio bitrate in videos
  36. - `set_video_audio_track_sample_rate` - Change audio sample rate in videos
  37. - `set_video_audio_track_channels` - Adjust audio channels in videos
  38. ### Creative Tools
  39. - `add_subtitles` - Burn subtitles with custom styling
  40. - `add_text_overlay` - Add dynamic text overlays with timing
  41. - `add_image_overlay` - Insert watermarks and logos
  42. - `add_b_roll` - Insert B-roll footage with transitions
  43. - `add_basic_transitions` - Apply fade in/out effects
  44. ### Advanced Editing
  45. - `concatenate_videos` - Join multiple videos with optional transitions
  46. - `change_video_speed` - Create slow-motion or time-lapse effects
  47. - `remove_silence` - Automatically remove silent segments
  48. - `health_check` - Verify server status
  49. ## 🚀 Quick Start
  50. ### Prerequisites (local installation)
  51. 1. **Python 3.8+** - [Download Python](https://www.python.org/downloads/)
  52. 2. **FFmpeg** - [Install FFmpeg](https://ffmpeg.org/download.html)
  53. 3. **uv** (recommended) - [Install uv](https://docs.astral.sh/uv/getting-started/installation/) or use pip
  54. ### Installation
  55. #### Option 1: Using Smithery (Easiest) ⭐
  56. The simplest way to get started is through the [Smithery MCP registry](https://smithery.ai/server/@misbahsy/video-audio-mcp):
  57. ![Clipboard-20250524-191433-493](https://github.com/user-attachments/assets/68b9d98c-6e3e-48fe-9337-d16f8e82e0d6)
  58. #### Option 2: Using uv (Recommended for Development)
  59. ```bash
  60. # Install uv if you haven't already
  61. curl -LsSf https://astral.sh/uv/install.sh | sh
  62. # Clone the repository
  63. git clone https://github.com/misbahsy/video-audio-mcp.git
  64. cd video-audio-mcp
  65. # Install dependencies with uv
  66. uv sync
  67. # Verify FFmpeg installation
  68. ffmpeg -version
  69. ```
  70. ### Running the Server
  71. ```bash
  72. # With uv (recommended)
  73. uv run server.py
  74. # Or with traditional python
  75. python server.py
  76. # Or with specific transport
  77. python -c "from server import mcp; mcp.run(transport='stdio')"
  78. ```
  79. ## 🔧 Client Configuration
  80. ### Claude Desktop (Recommended Configuration)
  81. Add to your `claude_desktop_config.json`:
  82. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  83. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  84. ```json
  85. {
  86. "mcpServers": {
  87. "VideoAudioServer": {
  88. "command": "uv",
  89. "args": [
  90. "--directory",
  91. "/path/to/your/video-audio-mcp",
  92. "run",
  93. "server.py"
  94. ]
  95. }
  96. }
  97. }
  98. ```
  99. **Alternative (using Python directly):**
  100. ```json
  101. {
  102. "mcpServers": {
  103. "VideoAudioServer": {
  104. "command": "python",
  105. "args": ["/path/to/video-audio-mcp/server.py"]
  106. }
  107. }
  108. }
  109. ```
  110. ### Cursor IDE (Recommended Configuration)
  111. 1. Open Cursor Settings: `File → Preferences → Cursor Settings → MCP`
  112. 2. Click "Add New Server"
  113. 3. Configure:
  114. - **Name**: `VideoAudioServer`
  115. - **Type**: `command`
  116. - **Command**: `uv --directory /path/to/your/video-audio-mcp run server.py`
  117. **Alternative configuration:**
  118. - **Command**: `/path/to/python /path/to/video-audio-mcp/server.py`
  119. ### Windsurf
  120. Add to your MCP configuration:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "VideoAudioServer": {
  125. "command": "uv",
  126. "args": [
  127. "--directory",
  128. "/path/to/your/video-audio-mcp",
  129. "run",
  130. "server.py"
  131. ],
  132. "env": {}
  133. }
  134. }
  135. }
  136. ```
  137. ### Why Use uv?
  138. The `uv` command is recommended because it:
  139. - **Automatically manages dependencies** without needing to activate virtual environments
  140. - **Faster installation** and dependency resolution
  141. - **Better isolation** - each project gets its own environment automatically
  142. - **More reliable** - handles Python version and dependency conflicts better
  143. - **Modern tooling** - the future of Python package management
  144. ### Using NPX (Alternative)
  145. For easier distribution, you can also run via npx if packaged:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "VideoAudioServer": {
  150. "command": "npx",
  151. "args": ["-y", "video-audio-mcp-server"]
  152. }
  153. }
  154. }
  155. ```
  156. ## 📖 Usage Examples
  157. ### Basic Video Editing
  158. ```
  159. "Can you convert this MP4 file to MOV format?"
  160. → Uses: convert_video_format
  161. "Trim the video from 30 seconds to 2 minutes"
  162. → Uses: trim_video
  163. "Extract the audio from this video as MP3"
  164. → Uses: extract_audio_from_video
  165. ```
  166. ### Advanced Editing Workflows
  167. ```
  168. "Create a highlight reel by concatenating these 3 clips with fade transitions"
  169. → Uses: concatenate_videos with transition effects
  170. "Add my logo watermark to the top-right corner of this video"
  171. → Uses: add_image_overlay
  172. "Remove all silent parts from this podcast recording"
  173. → Uses: remove_silence
  174. "Add subtitles to this video with custom styling"
  175. → Uses: add_subtitles
  176. ```
  177. ### Professional Workflows
  178. ```
  179. "Convert this 4K video to 1080p, reduce bitrate to 2Mbps, and change to H.265 codec"
  180. → Uses: convert_video_properties
  181. "Create a social media version: change to 9:16 aspect ratio, add text overlay, and compress"
  182. → Uses: change_aspect_ratio, add_text_overlay, set_video_bitrate
  183. "Insert B-roll footage at 30 seconds with a fade transition"
  184. → Uses: add_b_roll
  185. ```
  186. ## 🎯 Real-World Use Cases
  187. ### Content Creation
  188. - **YouTube Videos**: Automated editing, thumbnail generation, format optimization
  189. - **Social Media**: Aspect ratio conversion, text overlays, compression for platforms
  190. - **Podcasts**: Audio extraction, silence removal, format conversion
  191. ### Professional Video Production
  192. - **Corporate Videos**: Logo watermarking, subtitle addition, quality standardization
  193. - **Educational Content**: Screen recording processing, chapter markers, accessibility features
  194. - **Marketing Materials**: B-roll integration, transition effects, brand consistency
  195. ### Workflow Automation
  196. - **Batch Processing**: Convert entire video libraries to new formats
  197. - **Quality Control**: Standardize video properties across projects
  198. - **Archive Management**: Extract audio for transcription, create preview clips
  199. ## 🔍 Tool Reference
  200. ### Video Format Conversion
  201. ```python
  202. # Convert MP4 to MOV with specific properties
  203. convert_video_properties(
  204. input_video_path="input.mp4",
  205. output_video_path="output.mov",
  206. target_format="mov",
  207. resolution="1920x1080",
  208. video_codec="libx264",
  209. video_bitrate="5M",
  210. frame_rate=30
  211. )
  212. ```
  213. ### Text Overlays with Timing
  214. ```python
  215. # Add multiple text overlays with different timings
  216. add_text_overlay(
  217. video_path="input.mp4",
  218. output_video_path="output.mp4",
  219. text_elements=[
  220. {
  221. "text": "Welcome to our presentation",
  222. "start_time": "0",
  223. "end_time": "3",
  224. "font_size": 48,
  225. "font_color": "white",
  226. "x_pos": "center",
  227. "y_pos": "center"
  228. },
  229. {
  230. "text": "Chapter 1: Introduction",
  231. "start_time": "5",
  232. "end_time": "8",
  233. "font_size": 36,
  234. "box": True,
  235. "box_color": "black@0.7"
  236. }
  237. ]
  238. )
  239. ```
  240. ### Advanced Concatenation
  241. ```python
  242. # Join videos with crossfade transition
  243. concatenate_videos(
  244. video_paths=["clip1.mp4", "clip2.mp4"],
  245. output_video_path="final.mp4",
  246. transition_effect="dissolve",
  247. transition_duration=1.5
  248. )
  249. ```
  250. ## 🛡️ Error Handling
  251. The server includes comprehensive error handling:
  252. - **File Validation**: Checks for file existence before processing
  253. - **Format Support**: Validates supported formats and codecs
  254. - **Graceful Fallbacks**: Attempts codec copying before re-encoding
  255. - **Detailed Logging**: Provides clear error messages for troubleshooting
  256. ## 🔧 Troubleshooting
  257. ### Common Issues
  258. **FFmpeg not found**
  259. ```bash
  260. # Install FFmpeg
  261. # macOS: brew install ffmpeg
  262. # Ubuntu: sudo apt install ffmpeg
  263. # Windows: Download from https://ffmpeg.org/
  264. ```
  265. **Permission errors**
  266. ```bash
  267. # Ensure file permissions
  268. chmod +x server.py
  269. ```
  270. **MCP server not connecting**
  271. 1. Check file paths in configuration
  272. 2. Verify Python environment
  273. 3. Test server manually: `python server.py`
  274. 4. Check client logs for detailed errors
  275. ### Debug Mode
  276. Run with debug logging:
  277. ```bash
  278. python server.py --log-level DEBUG
  279. ```
  280. ## 🧪 Testing
  281. 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.
  282. ### Test Coverage
  283. The test suite covers:
  284. - **✅ Core Functions**: All 30+ video/audio editing tools
  285. - **🎬 Video Operations**: Format conversion, trimming, resolution changes, codec switching
  286. - **🎵 Audio Processing**: Bitrate adjustment, sample rate changes, channel configuration
  287. - **🎨 Creative Tools**: Text overlays, image watermarks, subtitle burning
  288. - **🔗 Advanced Features**: Video concatenation, B-roll insertion, transitions
  289. - **⚡ Performance**: Speed changes, silence removal, aspect ratio adjustments
  290. - **🛡️ Error Handling**: Invalid inputs, missing files, unsupported formats
  291. ### Running Tests
  292. #### Prerequisites for Testing
  293. ```bash
  294. # Install test dependencies
  295. pip install pytest
  296. # Ensure FFmpeg is installed and accessible
  297. ffmpeg -version
  298. ```
  299. #### Basic Test Execution
  300. ```bash
  301. # Run all tests
  302. pytest tests/
  303. # Run with verbose output
  304. pytest tests/ -v
  305. # Run specific test file
  306. pytest tests/test_video_functions.py
  307. # Run specific test function
  308. pytest tests/test_video_functions.py::test_extract_audio
  309. ```
  310. #### Advanced Test Options
  311. ```bash
  312. # Run tests with detailed output and no capture
  313. pytest tests/ -v -s
  314. # Run tests and stop on first failure
  315. pytest tests/ -x
  316. # Run tests with coverage report
  317. pytest tests/ --cov=server
  318. # Run only failed tests from last run
  319. pytest tests/ --lf
  320. ```
  321. ### Test Environment Setup
  322. The test suite automatically creates:
  323. - **Sample Files**: Test videos, audio files, and images
  324. - **Output Directory**: `tests/test_outputs/` for generated files
  325. - **Temporary Files**: B-roll clips and transition test materials
  326. ```bash
  327. # Test files are created in:
  328. tests/
  329. ├── test_outputs/ # Generated test results
  330. ├── sample_files/ # Auto-generated sample media
  331. ├── test_video_functions.py # Main test suite
  332. └── sample.mp4 # Primary test video (if available)
  333. ```
  334. ### Sample Test Output
  335. ```bash
  336. $ pytest tests/test_video_functions.py -v
  337. tests/test_video_functions.py::test_health_check PASSED
  338. tests/test_video_functions.py::test_extract_audio PASSED
  339. tests/test_video_functions.py::test_trim_video PASSED
  340. tests/test_video_functions.py::test_convert_audio_properties PASSED
  341. tests/test_video_functions.py::test_convert_video_properties PASSED
  342. tests/test_video_functions.py::test_add_text_overlay PASSED
  343. tests/test_video_functions.py::test_add_subtitles PASSED
  344. tests/test_video_functions.py::test_concatenate_videos PASSED
  345. tests/test_video_functions.py::test_add_b_roll PASSED
  346. tests/test_video_functions.py::test_add_basic_transitions PASSED
  347. tests/test_video_functions.py::test_concatenate_videos_with_xfade PASSED
  348. ========================= 25 passed in 45.2s =========================
  349. ```
  350. ### Test Categories
  351. #### 🎯 **Core Functionality Tests**
  352. - Video format conversion and property changes
  353. - Audio extraction and processing
  354. - File trimming and basic operations
  355. #### 🎨 **Creative Feature Tests**
  356. - Text overlay positioning and timing
  357. - Image watermark placement and opacity
  358. - Subtitle burning with custom styling
  359. #### 🔗 **Advanced Editing Tests**
  360. - Multi-video concatenation with transitions
  361. - B-roll insertion with various positions
  362. - Speed changes and silence removal
  363. #### 🛡️ **Error Handling Tests**
  364. - Invalid file paths and missing files
  365. - Unsupported formats and codecs
  366. - Edge cases and boundary conditions
  367. ### Writing Custom Tests
  368. To add new tests for additional functionality:
  369. ```python
  370. def test_new_feature():
  371. """Test description"""
  372. # Setup
  373. input_file = "path/to/test/file.mp4"
  374. output_file = os.path.join(OUTPUT_DIR, "test_output.mp4")
  375. # Execute
  376. result = your_new_function(input_file, output_file, parameters)
  377. # Validate
  378. assert "success" in result.lower()
  379. assert os.path.exists(output_file)
  380. # Optional: Validate output properties
  381. duration = get_media_duration(output_file)
  382. assert duration > 0
  383. ```
  384. ### Continuous Integration
  385. The test suite is designed to work in CI/CD environments:
  386. ```yaml
  387. # Example GitHub Actions workflow
  388. - name: Install FFmpeg
  389. run: sudo apt-get install ffmpeg
  390. - name: Install dependencies
  391. run: pip install -r requirements.txt pytest
  392. - name: Run tests
  393. run: pytest tests/ -v
  394. ```
  395. ### Performance Testing
  396. Some tests include performance validation:
  397. - **Duration Checks**: Verify output video lengths match expectations
  398. - **Quality Validation**: Ensure format conversions maintain quality
  399. - **File Size Monitoring**: Check compression and bitrate changes
  400. ### Test Data Management
  401. - **Automatic Cleanup**: Tests clean up temporary files
  402. - **Sample Generation**: Creates test media files as needed
  403. - **Deterministic Results**: Tests produce consistent, reproducible results
  404. > **💡 Tip**: Run tests after any changes to ensure functionality remains intact. The comprehensive test suite catches most issues before they reach production.
  405. ## 🤝 Contributing
  406. We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
  407. ### Development Setup
  408. ```bash
  409. # Clone and setup development environment
  410. git clone https://github.com/misbahsy/video-audio-mcp.git
  411. cd video-audio-mcp
  412. # Create virtual environment
  413. python -m venv venv
  414. source venv/bin/activate # On Windows: venv\Scripts\activate
  415. # Install development dependencies
  416. pip install -r requirements-dev.txt
  417. # Run tests
  418. pytest tests/
  419. ```
  420. ## 📄 License
  421. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  422. ## 🙏 Acknowledgments
  423. - Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
  424. - Powered by [FFmpeg](https://ffmpeg.org/) for media processing
  425. - Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/) specification
  426. ## 📞 Support
  427. - 🐛 **Bug Reports**: [GitHub Issues](https://github.com/misbahsy/video-audio-mcp/issues)
  428. ---
  429. **Made with ❤️ for the MCP community**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.