MoviePy MCP Server
README.md
# 🎬 MoviePy MCP Server — Professional Documentation
<div align="center">
[](https://modelcontextprotocol.io)
**A production‑grade MCP (Model Context Protocol) server that exposes 40+ video editing, animation, and audio processing tools to AI agents.**
</div>
---
## 📖 Table of Contents
- [🎬 MoviePy MCP Server — Professional Documentation](#-moviepy-mcp-server--professional-documentation)
- [📖 Table of Contents](#-table-of-contents)
- [📌 Overview](#-overview)
- [🏗️ Architecture](#️-architecture)
- [📦 Key Components](#-key-components)
- [🚀 Getting Started](#-getting-started)
- [✅ Prerequisites](#-prerequisites)
- [📥 Installation](#-installation)
- [🧪 Quick Test](#-quick-test)
- [⚙️ Configuration](#️-configuration)
- [🔧 MCP Client Configuration](#-mcp-client-configuration)
- [🌱 Environment Variables](#-environment-variables)
- [🛠️ Tool Reference](#️-tool-reference)
- [🎥 Video Editing Tools](#-video-editing-tools)
- [✍️ Text \& Overlay Tools](#️-text--overlay-tools)
- [🔊 Audio Tools](#-audio-tools)
- [🎨 Animation \& Generation Tools](#-animation--generation-tools)
- [🛠️ Utility Tools](#️-utility-tools)
- [📊 Workflow Diagrams](#-workflow-diagrams)
- [General Video Editing Pipeline](#general-video-editing-pipeline)
- [Custom Animation Rendering](#custom-animation-rendering)
- [Animation Expression Evaluation](#animation-expression-evaluation)
- [💡 Examples](#-examples)
- [🎬 1. Create a Full Animated Scene](#-1-create-a-full-animated-scene)
- [🏃 2. Generate a Stick Figure Running](#-2-generate-a-stick-figure-running)
- [✂️ 3. Edit an Existing Video](#️-3-edit-an-existing-video)
- [🔊 4. Extract and Process Audio](#-4-extract-and-process-audio)
- [🖼️ 5. Picture‑in‑Picture](#️-5-pictureinpicture)
- [🧪 Performance \& Benchmarks](#-performance--benchmarks)
- [⚠️ Error Handling](#️-error-handling)
- [🤝 Contributing](#-contributing)
- [🧑💻 Development Setup](#-development-setup)
- [⚡ TL;DR](#-tldr)
- [📄 License](#-license)
---
## 📌 Overview
<span style="color:#4CAF50;">**MoviePy MCP Server**</span> is a bridge between AI agents and professional video editing. Built on [FastMCP](https://github.com/jlowin/fastmcp) and [MoviePy](https://zulko.github.io/moviepy/), it provides a comprehensive suite of tools for:
- ✂️ **Video trimming, concatenation, and transformation**
- 🎨 **Procedural animation generation**
- 🔊 **Audio processing and mixing**
- 🖼️ **Overlay composition (text, images, PiP)**
- 🧩 **Custom animation with mathematical expressions**
- 🛠️ **Utility functions (thumbnail, frame extraction, conversion)**
All tools are exposed via the standard MCP protocol, making them callable by any MCP‑compatible client (e.g., Claude Desktop, custom agents).
---
## 🏗️ Architecture
The system is structured in layers, ensuring separation of concerns and scalability.
```mermaid
graph TB
subgraph "AI Agent Layer"
A[AI Assistant] --> B[MCP Client]
end
subgraph "MCP Server Layer"
B --> C["FastMCP Server<br>main.py"]
C --> D["Tool Registry<br>@mcp.tool() decorators"]
D --> E1[Video Tools]
D --> E2[Audio Tools]
D --> E3[Animation Tools]
D --> E4[Utility Tools]
end
subgraph "Core Processing Layer"
E1 --> F[MoviePy Core]
E2 --> F
E3 --> F
E4 --> F
F --> G["FFmpeg Backend<br>via imageio-ffmpeg"]
G --> H["Output Files<br>.mp4, .mp3, .png"]
end
subgraph "Storage Layer"
H --> I[("moviepy_outputs/<br>uuid-named files")]
end
style A fill:#4CAF50,color:#fff
style C fill:#2196F3,color:#fff
style F fill:#FF9800,color:#fff
style G fill:#9E9E9E,color:#fff
```
### 📦 Key Components
| Component | Description |
|-----------|-------------|
| **FastMCP** | Manages the server lifecycle, tool registration, and protocol handling |
| **MoviePy** | Core video manipulation library (editing, compositing, effects) |
| **Pillow** | Image creation and rendering (for frame‑by‑frame animation) |
| **NumPy** | Fast numerical operations for pixel‑level manipulation |
| **FFmpeg** | Underlying encoder/decoder (managed by imageio‑ffmpeg) |
---
## 🚀 Getting Started
### ✅ Prerequisites
- **Python 3.12+** (required for the project’s dependencies)
- **`uv`** – the fast Python package installer and resolver
- **FFmpeg** – installed automatically via `imageio-ffmpeg`, but you can also install it manually if needed.
### 📥 Installation
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/MoviePy_MCP.git
cd MoviePy_MCP
```
2. **Install dependencies**
```bash
uv sync
```
This will install all dependencies defined in `pyproject.toml`.
3. **Verify the installation**
```bash
uv run python main.py
```
You should see:
```
MoviePy MCP Server
Output directory: /path/to/moviepy_outputs
Starting MCP server...
```
### 🧪 Quick Test
To ensure everything works, you can run a simple tool call via any MCP client. Alternatively, test the animation engine directly:
```python
# In a Python script (or from the REPL after importing main)
from main import create_stick_figure_runner
video_path = create_stick_figure_runner(duration=3)
print(f"Video generated: {video_path}")
```
---
## ⚙️ Configuration
### 🔧 MCP Client Configuration
The server is designed to be launched by an MCP client (e.g., Claude Desktop, Cursor, etc.). Provide a configuration file similar to `Config_Example.json`:
```json
{
"MoviePy_MCP": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/MoviePy_MCP",
"run",
"main.py"
]
}
}
```
### 🌱 Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `OUTPUT_DIR` | Output directory for all generated files | `moviepy_outputs/` |
| `FPS` | Default frames per second for new videos | `30` |
| `VIDEO_CODEC` | Video codec for exports | `libx264` |
| `AUDIO_CODEC` | Audio codec | `aac` |
| `PRESET` | FFmpeg preset (ultrafast, fast, medium, slow) | `medium` |
> 💡 *You can set these in your shell before starting the server.*
---
## 🛠️ Tool Reference
All tools are exposed as MCP tools with clear parameter names, types, and docstrings. The complete list is organised by category.
### 🎥 Video Editing Tools
| Tool | Description | Parameters | Return |
|------|-------------|------------|--------|
| `get_video_info` | Retrieve metadata (duration, dimensions, fps) | `input_path: str` | `dict` with video info |
| `trim_video` | Extract a segment between `start` and `end` seconds | `input_path: str, start: float, end: float, output_path: str = ""` | `dict` with status and output path |
| `change_speed` | Adjust playback speed (`0.5` = slow, `2.0` = fast) | `input_path: str, speed: float, output_path: str = ""` | `dict` with status and speed applied |
| `resize_video` | Resize by scale or explicit dimensions | `input_path: str, width: int = 0, height: int = 0, scale: float = 0, output_path: str = ""` | `dict` with status and output path |
| `rotate_video` | Rotate by given angle (degrees) | `input_path: str, angle: float, output_path: str = ""` | `dict` with status and output path |
| `mirror_video` | Mirror horizontally or vertically | `input_path: str, direction: str = "horizontal", output_path: str = ""` | `dict` with status and output path |
| `crop_video` | Crop to a rectangular region (pixel coordinates) | `input_path: str, x1: int, y1: int, x2: int, y2: int, output_path: str = ""` | `dict` with status and output path |
| `merge_videos` | Concatenate multiple videos in order | `input_paths: list[str], output_path: str = ""` | `dict` with status and clip count |
| `reverse_video` | Reverse the video playback | `input_video: str` | `str` path to reversed video |
| `loop_video` | Repeat the video N times | `input_video: str, loops: int = 2` | `str` path to looped video |
| `split_video` | Split at a given time, output two files | `input_video: str, split_time: float` | `dict` with `part_1` and `part_2` paths |
| `freeze_frame` | Hold a specific frame for a duration | `input_video: str, freeze_time: float, freeze_duration: float = 2` | `str` path to output video |
| `fade_video` | Apply fade‑in and/or fade‑out | `input_video: str, fade_in: float = 1, fade_out: float = 1` | `str` path to output video |
| `crossfade_videos` | Crossfade between two videos | `video1: str, video2: str, transition_duration: float = 1` | `str` path to output video |
---
### ✍️ Text & Overlay Tools
| Tool | Description | Parameters | Return |
|------|-------------|------------|--------|
| `add_text` | Add text overlay to a video | `input_path: str, text: str, fontsize: int = 60, color: str = "white", position: str = "center", start: float = 0, duration: float = 5, output_path: str = ""` | `dict` with status and output path |
| `add_image_overlay` | Overlay an image on the video | `input_path: str, image_path: str, x: int = 0, y: int = 0, start: float = 0, duration: float = 5, scale: float = 1.0, opacity: float = 1.0, output_path: str = ""` | `dict` with status and output path |
| `picture_in_picture` | Place one video inside another | `main_video: str, small_video: str, x: int = 20, y: int = 20, scale: float = 0.3, start: float = 0, duration: float = 0, output_path: str = ""` | `dict` with status and output path |
---
### 🔊 Audio Tools
| Tool | Description | Parameters | Return |
|------|-------------|------------|--------|
| `add_audio` | Add or replace audio track | `input_path: str, audio_path: str, volume: float = 1.0, output_path: str = ""` | `dict` with status and output path |
| `fade_audio` | Apply audio fade‑in/out | `input_path: str, fade_in: float = 0, fade_out: float = 0, output_path: str = ""` | `dict` with status and output path |
| `remove_audio` | Strip audio from video | `input_video: str` | `str` path to silent video |
| `replace_audio` | Replace existing audio with a new file | `input_video: str, audio_file: str` | `str` path to output video |
| `adjust_volume` | Change audio volume (0.0 = mute, 2.0 = double) | `input_video: str, volume: float = 1.0` | `str` path to output video |
| `extract_audio` | Extract audio as MP3 | `input_video: str` | `str` path to MP3 file |
---
### 🎨 Animation & Generation Tools
| Tool | Description | Parameters | Return |
|------|-------------|------------|--------|
| `create_custom_animation` | General‑purpose multi‑object animation engine | `duration: float = 5, width: int = 1280, height: int = 720, fps: int = 30, background: str = "#101018", objects: list = None, output_name: str = "custom_animation"` | `str` path to generated video |
| `create_stick_figure_runner` | Pre‑built animated running stick figure | `duration: float = 5, width: int = 1280, height: int = 720, background: str = "#87CEEB"` | `str` path to video |
| `create_animated_scene` | Simple animated scenes (bouncing, horizontal, orbit, pulse, etc.) | `scene_type: str = "bouncing", duration: float = 5, width: int = 1280, height: int = 720, background: str = "#101018", object_color: str = "#ffffff"` | `str` path to video |
| `create_moving_object_video` | Moving geometric shape (circle, square, triangle) | `duration: float = 5, width: int = 1280, height: int = 720, object_type: str = "circle", background: str = "#111111", object_color: str = "#ffffff"` | `str` path to video |
| `create_particle_animation` | Particle field with random motion | `duration: float = 5, width: int = 1280, height: int = 720, particle_count: int = 100, background: str = "#050510"` | `str` path to video |
| `create_animated_text` | Text with various animation styles (fade, slide, zoom) | `text: str, duration: float = 5, width: int = 1280, height: int = 720, font_size: int = 80, background: str = "#000000", text_color: str = "white", animation: str = "fade"` | `str` path to video |
| `create_slideshow_video` | Create a video from a list of images | `image_paths: list, seconds_per_image: float = 3, transition: str = "fade"` | `str` path to video |
| `create_gradient_animation` | Animated moving colour gradient | `duration: float = 5, width: int = 1280, height: int = 720` | `str` path to video |
| `create_countdown_video` | Countdown from N to 1 | `seconds: int = 5, width: int = 1280, height: int = 720, background: str = "#000000"` | `str` path to video |
| `create_typing_text_video` | Typewriter‑style text appearance | `text: str, duration: float = 5, width: int = 1280, height: int = 720, font_size: int = 60` | `str` path to video |
| `create_bouncing_object` | Physics‑based bouncing ball animation | `duration: float = 5, width: int = 1280, height: int = 720, gravity: float = 900` | `str` path to video |
| `create_progress_bar_video` | Animated progress/loading bar | `duration: float = 5, width: int = 1280, height: int = 720` | `str` path to video |
| `create_background` | Solid colour video background | `width: int = 1280, height: int = 720, duration: float = 5, r: int = 0, g: int = 0, b: int = 0, output_path: str = ""` | `dict` with status and output path |
| `create_text_video` | Complete video with centred text | `text: str, duration: float = 5, width: int = 1280, height: int = 720, fontsize: int = 80, text_color: str = "white", background_color: tuple[int, int, int] = (0, 0, 0), output_path: str = ""` | `dict` with status and output path |
---
### 🛠️ Utility Tools
| Tool | Description | Parameters | Return |
|------|-------------|------------|--------|
| `export_video` | Re‑encode video with quality preset | `input_path: str, output_path: str = "", fps: int = 30, quality: str = "medium"` | `dict` with status and output path |
| `create_thumbnail` | Extract a frame as PNG | `input_video: str, time: float = 0` | `str` path to PNG |
| `extract_frame` | Extract a specific frame as PNG | `input_video: str, time: float` | `str` path to PNG |
| `zoom_animation` | Smooth zoom‑in effect | `input_video: str, zoom_amount: float = 1.3` | `str` path to output video |
| `pan_animation` | Pan across the video (left/right/up/down) | `input_video: str, direction: str = "left"` | `str` path to output video |
---
## 📊 Workflow Diagrams
### General Video Editing Pipeline
```mermaid
flowchart TD
A[Start] --> B[Load Input Video]
B --> C{Choose Operation}
C -->|Trim| D[Set start/end]
C -->|Speed| E[Set speed factor]
C -->|Resize| F[Set new dimensions]
C -->|Rotate| G[Set angle]
C -->|Merge| H[Load multiple videos]
C -->|Overlay| I[Add text/image]
D --> J[Process with MoviePy]
E --> J
F --> J
G --> J
H --> J
I --> J
J --> K[Write output with FFmpeg]
K --> L[Save to moviepy_outputs/]
L --> M[Return file path]
```
### Custom Animation Rendering
```mermaid
flowchart LR
subgraph Input
A[Object definitions]
B[Duration, resolution, fps]
C[Background colour]
end
subgraph Processing
D[Parse object list]
E[For each frame t]
F[Evaluate expressions<br/>with t]
G[Render each object<br/>on a PIL canvas]
H[Composite all objects]
I[Convert to NumPy array]
end
subgraph Output
J[Create MoviePy VideoClip]
K[FFmpeg encoding]
L[Output .mp4 file]
end
A --> D
B --> D
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J
J --> K
K --> L
```
### Animation Expression Evaluation
```mermaid
flowchart TD
A["Expression String<br>e.g., '300 + 100*sin(t*4)'"] --> B[AST Parse]
B --> C{Safe?}
C -->|Yes| D[Evaluate with t]
C -->|No| E[Raise ValueError]
D --> F[Return numeric value]
subgraph "Allowed Functions & Operators"
G[+, -, *, /, **, %]
H[sin, cos, tan, abs, sqrt]
I[min, max, pi]
end
F --> G
F --> H
F --> I
```
---
## 💡 Examples
### 🎬 1. Create a Full Animated Scene
```python
result = create_custom_animation(
duration=5,
width=1280,
height=720,
background="#1a1a2e",
objects=[
{
"type": "circle",
"x": {"expression": "640 + 300*sin(t*2)"},
"y": {"expression": "360 + 200*cos(t*1.5)"},
"radius": 40,
"color": "#ff6b6b",
"rotation": {"expression": "t*60"}
},
{
"type": "rectangle",
"x": {"expression": "640 + 200*cos(t*3)"},
"y": {"expression": "360 + 150*sin(t*2.5)"},
"width": 80,
"height": 80,
"color": "#4ecdc4",
"rotation": {"expression": "t*90"}
},
{
"type": "text",
"text": "🎬 AI Animation",
"x": 640,
"y": 80,
"font_size": 64,
"color": "#ffffff"
}
]
)
print(f"Video saved to: {result}")
```
### 🏃 2. Generate a Stick Figure Running
```python
video = create_stick_figure_runner(
duration=4,
width=800,
height=600,
background="#a8d8ea"
)
```
### ✂️ 3. Edit an Existing Video
```python
# Trim, speed up, and add a watermark
info = get_video_info("input.mp4")
trimmed = trim_video("input.mp4", start=10, end=30)
fast = change_speed(trimmed["output"], speed=1.5)
watermarked = add_text(
fast["output"],
text="© 2026 My Studio",
fontsize=40,
color="white",
position=("right", "bottom")
)
```
### 🔊 4. Extract and Process Audio
```python
# Extract audio, then add it back with volume boost
audio_path = extract_audio("video.mp4")
video_with_audio = add_audio("video.mp4", audio_path, volume=1.8)
```
### 🖼️ 5. Picture‑in‑Picture
```python
result = picture_in_picture(
main_video="presentation.mp4",
small_video="speaker.mp4",
x=20,
y=20,
scale=0.25
)
```
---
## 🧪 Performance & Benchmarks
Tests were performed on a **MacBook Pro M1, 16GB RAM** with SSD storage. Average times for common operations:
| Operation | Duration | File Size (approx) | CPU Usage |
|-----------|----------|-------------------|-----------|
| Trim 10‑sec segment | 2.1 s | 5.2 MB | ~80% |
| Change speed (2×) | 2.8 s | 3.0 MB | ~85% |
| Resize 720p → 480p | 3.0 s | 2.1 MB | ~75% |
| Rotate 90° | 3.5 s | 6.0 MB | ~80% |
| Merge two 10‑sec clips | 4.2 s | 10.5 MB | ~90% |
| Add text overlay | 2.5 s | 5.8 MB | ~70% |
| Custom animation (5 sec, 3 objects) | 5.0 s | 4.0 MB | ~95% |
| Particle animation (100 particles) | 4.5 s | 3.5 MB | ~90% |
> **Note:** Times depend on input file size, codec, and system load. The server uses `libx264` with `medium` preset by default.
---
## ⚠️ Error Handling
The server implements robust error checking:
- **File Existence:** All `input_path` parameters are validated before processing.
- **Invalid Parameters:** Type and range checks (e.g., positive duration, non‑zero speed) raise descriptive `ValueError`.
- **Audio Presence:** Audio‑related tools will fail gracefully if the video has no audio track.
- **Expression Safety:** Animation expressions are parsed with `ast` and a whitelist of functions/operators to prevent arbitrary code execution.
- **Output Directory:** The `moviepy_outputs/` directory is created automatically.
All errors are returned as structured MCP error responses (or raised as exceptions during tool execution).
---
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. **Fork** the repository.
2. **Create a feature branch** (`git checkout -b feature/your-feature`).
3. **Commit** your changes with clear messages.
4. **Push** to the branch (`git push origin feature/your-feature`).
5. **Open a Pull Request** against the `main` branch.
### 🧑💻 Development Setup
### ⚡ TL;DR
```bash
# Clone your fork
git clone https://github.com/yourusername/MoviePy_MCP.git
cd MoviePy_MCP
# Install with dev dependencies
uv sync
#Run Main.py script
uv run main.py
```
---
## 📄 License
This project is licensed under the **MIT License** – see the [LICENSE](LICENSE) file for details.
---
<div align="center">
**Made with ❤️ by Sahil Kumar**
[⬆ Back to Top](#-moviepy-mcp-server-professional-documentation)
</div>TDQS
C2.7/5.0
Scored across 42 tools
Disambiguation2/5
Several tools blur together: add_audio explicitly includes 'add or replace', overlapping with replace_audio; create_thumbnail and extract_frame both save a PNG frame; and create_custom_animation is a general-purpose engine that can reproduce many dedicated generators like create_bouncing_object, create_animated_scene, and create_animated_text. The editing tools are mostly distinct, but the creation tools have serious boundary confusion.
Naming Consistency4/5
The vast majority of tools follow a clean snake_case verb_noun pattern: create_, add_, get_, trim_, resize_, merge_, etc. The only notable deviation is picture_in_picture, which uses a noun phrase without a leading verb, but overall the naming is predictable and consistent.
Tool Count2/5
42 tools is well beyond the well-scoped range for an MCP server. Many of the creation tools are highly redundant template variations that could be consolidated into a smaller set, especially since create_custom_animation already provides generalized procedural animation.
Completeness4/5
The server covers a broad video editing lifecycle: importing/inspecting video, trimming, splitting, merging, transforming, audio editing, overlays, effects, and export. Minor gaps like color filters, subtitle support, or additional export formats exist, but most common video editing workflows are supported without dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo issues