MoviePy MCP Server

An LLM-friendly Model Context Protocol server for video and audio editing, built on MoviePy v2 and FastMCP. It lets MCP clients (Claude Desktop, Claude Code, Cursor, etc.) trim, merge, resize, overlay, mix audio, and render video through natural language.

Design

The server is built around an in-memory clip registry:

1. load_video / load_audio / load_image returns a clip_id.

2. Every editing tool takes a clip_id and returns a new clip_id — operations chain without touching disk, and source clips are never mutated, so an agent can branch or retry any step.

3. export_clip is the only tool that renders a file.

Every tool returns uniform metadata (duration_seconds, size, fps, has_audio, history), so the model always knows the state of an edit without extra probing. Errors are actionable: they name the bad argument, list known clip_ids, and suggest the fix.

Requirements

• Python 3.10+

• FFmpeg on your PATH (sudo apt install ffmpeg / brew install ffmpeg)

Installation

git clone <your-repo-url> moviepy-mcp
cd moviepy-mcp
pip install -e .
# or with uv:
uv pip install -e .

Run it directly to verify:

moviepy-mcp

Client configuration

Cursor (~/.cursor/mcp.json)

Add a moviepy entry under mcpServers (same shape as other local uv servers). Restart Cursor or reload MCP after saving:

{
  "mcpServers": {
    "moviepy": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/vivek/projects/moviepy-mcp",
        "python",
        "src/moviepy_mcp/server.py"
      ]
    }
  }
}

Replace the --directory path with your clone of this repo. uv run uses the project’s pyproject.toml / .venv, so you do not need a global moviepy-mcp install.

Claude Desktop / Claude Code (stdio)

If the package is installed (pip install -e . or uv pip install -e .):

{
  "mcpServers": {
    "moviepy": {
      "command": "moviepy-mcp"
    }
  }
}

Or without installing, via uv (one-shot deps):

{
  "mcpServers": {
    "moviepy": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "moviepy",
        "python",
        "/path/to/moviepy-mcp/src/moviepy_mcp/server.py"
      ]
    }
  }
}

Tools

Example agent workflow

"Take intro.mp4, keep seconds 5–20, add the title 'Q2 Review' for the first 4 seconds, fade out at the end, and save as final.mp4."

The agent will typically call:

load_video(path="intro.mp4")                          -> video_a1b2c3d4
trim(clip_id="video_a1b2c3d4", start_seconds=5, end_seconds=20)
create_text_clip(text="Q2 Review", font_size=64, duration_seconds=4)
overlay_clip(base_clip_id=..., overlay_clip_id=..., position="top")
preview_frame(clip_id=..., time_seconds=0)
export_clip(clip_id=..., output_path="final.mp4")

Notes

• Text rendering requires a font; pass font="/path/to/font.ttf" to create_text_clip if the default is unavailable on your system.

• GIF export uses write_gif (defaults to 12 fps); everything else goes through FFmpeg.

• The registry lives in server memory — restarting the server clears all clip_ids.

• preview_frame returns an image to the model (downscaled to 640px by default). Use it after edits to verify before export_clip.

• Clip metadata and a first-frame PNG are resources: clip://{clip_id}/info and clip://{clip_id}/frame.

• crossfade dissolves overlapping clips; concatenate is still a hard cut.

• even_size crops odd dimensions (H.264). add_subtitles accepts SRT or WebVTT via srt_text or srt_path.

• download_video uses yt-dlp for YouTube and Instagram. Public URLs work as-is; private Instagram media may need cookies_from_browser (e.g. chrome) or a cookies_file. Respect each platform's terms of service and only download content you have rights to use.

• reframe changes aspect ratio for Shorts/Reels-style output: mode="crop" center-crops to fill, mode="pad_blur" keeps the whole frame and fills the bars with a blurred, zoomed copy.

• create_slideshow builds a video from a list of image paths in one call, with optional crossfade transitions and background audio (looped or trimmed to fit).

• mix_audio_tracks layers audio clips simultaneously (voice + music + SFX) with per-track volume; concatenate still plays clips one after another.

• remove_silence cuts near-silent gaps out of an audio or video clip (podcast/vlog jump-cut editing) based on a loudness threshold and minimum gap length.

• save_frame and export_image take at_end=True to grab the last frame without knowing the exact duration.

License

MIT