vidMagik-mcp

You can run vidMagik-mcp to expose 70+ MoviePy-based tools via a reusable MCP interface. This server lets you perform video editing, compositing, effects, and audio processing through simple MCP client commands, with stdio transport as the default for seamless integration.

How to use

You interact with the vidMagik MCP server through an MCP client. Start the server using the provided stdio command, then connect from your MCP client to issue tools for loading, generating, composing, applying effects, and exporting final media. You can also opt to run the server inside a Docker container for easier dependency management. Use the documented transport options to switch to HTTP or SSE if your use case requires remote access.

How to install

Prerequisites: ensure you have Python 3.12 or newer, FFmpeg installed, ImageMagick for text and credits clips, and uvx as the MCP package manager.

Step-by-step setup using the repository scaffolding or Docker is provided below.

# Clone the project
git clone https://github.com/vizionik25/vidMagik-mcp.git
cd vidMagik-mcp

# Install runtime dependencies (via uvx)
uv sync

Running the server with stdio transport

You can start the server in local mode using stdio transport with the following command.

uv run main.py

Running the server with HTTP or SSE transport

If you prefer remote access via HTTP or SSE, start the server with the desired transport settings.

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

Configure your MCP client to connect to vidMagik-mcp using the stdio or HTTP/SSE endpoints shown above. The client should reference the same command and transport that you started locally.

Docker setup option

Docker bundles FFmpeg, ImageMagick, and all system dependencies. Use the container as an MCP server to simplify setup.

# Quick start: build and run in stdio mode
docker compose up --build

# Using MCP with Docker as the server
# Example client config:
{
  "mcpServers": {
    "vidMagik": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-i", "mcp-moviepy"],
      "cwd": "/path/to/vidMagik-mcp"
    }
  }
}

State management

vidMagik MCP maintains in-memory clips to enable fast, chained editing operations. Each tool that creates or modifies a clip returns a clip_id, which you pass to subsequent tools for further processing. You can view active clips with list_clips and free memory with delete_clip. The server automatically cleans memory to prevent excessive usage.

Notes on prompts and workflows

The server provides built-in prompts to guide complex workflows, such as creating professional slideshows, title cards, glitch effects, auto-framing for vertical videos, kaleidoscope animations, and more. Use these prompts to quickly compose multi-step edits.

Development and testing

Run the end-to-end tests to validate behavior across the MCP interface.

uv run pytest tests/test_e2e.py

License

MIT license.

Available tools

Load

Load various media clips such as video_file_clip, audio_file_clip, image_clip, and image_sequence_clip.

Generate

Create new clips using text, color, credits, subtitles, and drawing color utilities.

Export

Write out video, audio, and GIF exports using write_videofile, write_audiofile, and write_gif.

Fast Tools

Perform fast, lossless trims with tools_ffmpeg_extract_subclip.

Combine

Merge and compose video and audio clips with composite_video_clips, concatenate_video_clips, tools_clips_array, composite_audio_clips, and concatenate_audio_clips.

Refine

Fine-tune clips with subclip, vfx_resize, vfx_crop, and vfx_rotate.

Configure

Set position, audio, mask, start, end, and duration with set_position, set_audio, set_mask, set_start, set_end, and set_duration.

vfx_freeze

Apply a freeze-frame effect and related time-based transformations.

vfx_freeze_region

Freeze a specific region within a frame.

vfx_multiply_speed

Change playback speed by multiplying the clip speed.

vfx_time_mirror

Mirror the timeline to create reflective effects.

vfx_time_symmetrize

Symmetrize time to create mirrored motion.

vfx_loop

Create looping segments for seamless repetition.

vfx_make_loopable

Make a segment loopable for continuous playback.

vfx_accel_decel

Apply acceleration and deceleration to motion.

vfx_black_white

Convert to black and white visuals.

vfx_invert_colors

Invert the color channels for a negative-style look.

vfx_fade_in

Fade in at the start of a clip.

vfx_fade_out

Fade out at the end of a clip.

vfx_gamma_correction

Adjust gamma for brightness and contrast.

vfx_lum_contrast

Fine-tune luminance and contrast levels.

vfx_multiply_color

Multiply color channels for stylized color blends.

vfx_painting

Apply painterly motion effects.

vfx_blink

Create blinking visibility effects.

vfx_mirror_x

Mirror content across the horizontal axis.

vfx_mirror_y

Mirror content across the vertical axis.

vfx_even_size

Normalize size to even dimensions.

vfx_margin

Add margins around the clip.

vfx_scroll

Create scrolling or panoramic motion.

vfx_supersample

Supersample for higher quality rendering.

vfx_slide_in

Animate entrance from a side.

vfx_slide_out

Animate exit to a side.

vfx_head_blur

Apply blur to the moving head region.

vfx_mask_color

Mask by a specific color.

vfx_masks_and

Combine masks with logical AND.

vfx_masks_or

Combine masks with logical OR.

vfx_matrix

Classic Matrix rain overlay.

vfx_kaleidoscope

Radial symmetry with custom slices.

vfx_rgb_sync

Chromatic aberration with temporal offsets.

vfx_chroma_key

Green screen removal with threshold and softness.

vfx_auto_framing

Face/subject tracking for vertical video framing.

vfx_clone_grid

Multi-clone grid layouts (2x2, 4x4, etc.).

vfx_rotating_cube

3D perspective cube mapping.

vfx_quad_mirror

Four-way mirror symmetry.

vfx_kaleidoscope_cube

Radial symmetry with 3D rotation.

afx_multiply_volume

Adjust overall volume by a multiplier.

afx_multiply_stereo_volume

Scale left and right channel volumes independently.

afx_audio_fade_in

Fade audio in at the start of a clip.

afx_audio_fade_out

Fade audio out at the end of a clip.

afx_audio_delay

Introduce a delay to audio playback.

afx_audio_loop

Loop the audio segment.

afx_audio_normalize

Normalize volume to a target level.

tools_detect_scenes

Automatic scene cut detection for editing.

tools_find_video_period

Analyze video to detect repetitive motion periods.

tools_find_audio_period

Detect tempo or periodicity in audio.

tools_file_to_subtitles

Parse subtitle files into usable subtitle data.

tools_check_installation

Verify MoviePy and dependencies are properly installed.

text_clip

Create a text-based clip for titles or captions.

color_clip

Generate a solid color clip for backdrops or overlays.

credits_clip

Produce ending credits sequence.

subtitles_clip

Add subtitles to a video.