Skip to content
Conduit

mcp server

vidmagik-mcp

An un-official moviepy mcp server implementation including 70+ tools including a few custom advanced effects and a handful of prompts demonstrating how to use the custom advanced effects

vizionik25/vidmagik-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 23, 2026

vidMagik-mcp

MCP Python MoviePy

A Model Context Protocol (MCP) server that provides a comprehensive interface to MoviePy for video editing. Uses stdio transport by default for seamless integration with MCP clients.

Exposes 70+ tools for professional-grade video editing, compositing, effects, and audio processing.

Features

IO & Creation

  • Load: video_file_clip, audio_file_clip, image_clip, image_sequence_clip
  • Generate: text_clip, color_clip, credits_clip, subtitles_clip, tools_drawing_color_gradient, tools_drawing_color_split
  • Export: write_videofile, write_audiofile, write_gif
  • Fast Tools: tools_ffmpeg_extract_subclip (lossless trimming)

Compositing & Transformation

  • Combine: composite_video_clips, concatenate_video_clips, tools_clips_array, composite_audio_clips, concatenate_audio_clips
  • Refine: subclip, vfx_resize, vfx_crop, vfx_rotate
  • Configure: set_position, set_audio, set_mask, set_start, set_end, set_duration

Video Effects (vfx)

  • Time: vfx_freeze, vfx_freeze_region, vfx_multiply_speed, vfx_time_mirror, vfx_time_symmetrize, vfx_loop, vfx_make_loopable, vfx_accel_decel
  • Color: vfx_black_white, vfx_invert_colors, vfx_fade_in, vfx_fade_out, vfx_gamma_correction, vfx_lum_contrast, vfx_multiply_color, vfx_painting, vfx_blink
  • Geometry: vfx_mirror_x, vfx_mirror_y, vfx_even_size, vfx_margin, vfx_scroll, vfx_supersample
  • Motion: vfx_slide_in, vfx_slide_out, vfx_head_blur
  • Masking: vfx_mask_color, vfx_masks_and, vfx_masks_or

Custom Advanced Effects

  • vfx_matrix — Classic "Matrix" digital rain overlay
  • vfx_kaleidoscope — Radial symmetry with custom slices
  • vfx_rgb_sync — Chromatic aberration / glitch with temporal offsets
  • vfx_chroma_key — Green screen removal with threshold and softness
  • vfx_auto_framing — Face/subject tracking and cropping for vertical video
  • vfx_clone_grid — Multi-clone grid layout (2x2, 4x4, etc.)
  • vfx_rotating_cube — 3D perspective cube mapping
  • vfx_quad_mirror — Four-way mirror symmetry
  • vfx_kaleidoscope_cube — Radial symmetry combined with 3D rotation

Audio Effects (afx)

  • afx_multiply_volume, afx_multiply_stereo_volume, afx_audio_fade_in, afx_audio_fade_out, afx_audio_delay, afx_audio_loop, afx_audio_normalize

Analysis & Utilities

  • tools_detect_scenes — Automatic scene cut detection
  • tools_find_video_period — Frequency analysis for repetitive motion
  • tools_find_audio_period — Tempo/period detection for audio
  • tools_file_to_subtitles — Parse subtitle files
  • tools_check_installation — Verify MoviePy and dependencies

Prerequisites

  • Python 3.12+
  • FFmpeg — Required by MoviePy for video processing
  • ImageMagick — Required for text_clip and credits_clip
  • uv — Python package manager

Installation

git clone https://github.com/vizionik25/vidMagik-mcp.git
cd vidMagik-mcp
uv sync

Running the Server

The server uses stdio transport by default:

uv run main.py

To use HTTP or SSE transport instead:

uv run main.py --transport http --host 0.0.0.0 --port 8080
uv run main.py --transport sse --host 0.0.0.0 --port 8080

MCP Client Configuration

Add this to your MCP client config (e.g. Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "vidMagik-mcp": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/vidMagik-mcp"
    }
  }
}

Docker

Docker is the recommended approach — it bundles FFmpeg, ImageMagick, and all system dependencies automatically.

Quick Start

docker compose up --build

This builds the image and starts the server with stdio transport.

Media Directory

The ./media directory on your host is mounted to /app/media inside the container. Use it as the workspace for all input and output files:

mkdir -p media
# Place your source videos, images, and audio in ./media

When using MCP tools, reference files as media/filename.mp4. Output files written to media/ will appear on your host.

Docker MCP Client Configuration

To use the Docker container as an MCP server:

{
  "mcpServers": {
    "moviepy": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-i", "mcp-moviepy"],
      "cwd": "/path/to/mcp-moviepy"
    }
  }
}

Manual Docker Build & Run

docker build -t mcp-moviepy .
docker run -i -v $(pwd)/media:/app/media mcp-moviepy

State Management

The server maintains clips in memory:

  1. Clip IDs — Tools that create or modify clips return a clip_id (UUID string)
  2. Chaining — Pass clip_id to subsequent tools for further operations
  3. Management — Use list_clips to view active clips and delete_clip to free memory
  4. Limits — Auto memory cleanup with file count and total size limits to prevent OOM

Prompt Templates

Built-in prompts guide the LLM through complex workflows:

  • slideshow_wizard — Professional slideshow from images with transitions
  • title_card_generator — Title cards with text on solid backgrounds
  • glitch_effect_preset — High-energy RGB split glitch aesthetic
  • auto_framing_for_tiktok — Convert horizontal video to 9:16 vertical
  • matrix_intro_preset — Classic code-rain overlay
  • rotating_cube_transition — 3D spinning cube effect
  • demonstrate_kaleidoscope — Mesmerizing radial symmetry animation
  • demonstrate_kaleidoscope_cube — Hybrid kaleidoscope + 3D cube

Development

Run tests:

uv run pytest tests/test_e2e.py

License

MIT

↑↓ navigate openesc close