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 a 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 renders a file. preset can be youtube_1080p, reels_1080x1920, or podcast_aac.

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.

Reads and writes stay inside MOVIEPY_MCP_MEDIA_ROOT (your home directory when unset) or the system temp directory. The registry is one session on stdio. HTTP (MOVIEPY_MCP_TRANSPORT=http) gives each client its own registry and requires MOVIEPY_MCP_TOKEN. Source files are written to .moviepy-mcp/ under the workspace and reopened after a restart; project_status lists edits that were not rebuilt.

The default tool list is the everyday edit path. Set MOVIEPY_MCP_ADVANCED=1 to also expose blur, chroma key, Ken Burns, and the other effects.

Code is split under src/moviepy_mcp/: config, paths, registry, presets, editing, prompts, and tools/.

Related MCP server: Video Edit MCP Server

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",
        "moviepy-mcp"
      ],
      "env": {
        "MOVIEPY_MCP_MEDIA_ROOT": "C:/Users/vivek/Videos",
        "MOVIEPY_MCP_ADVANCED": "1"
      }
    }
  }
}

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:

{
  "mcpServers": {
    "moviepy": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/moviepy-mcp",
        "moviepy-mcp"
      ]
    }
  }
}

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.

• Source clips are reopened from .moviepy-mcp/*.json after a restart. Derived edits are listed by project_status and are not rebuilt. Set MOVIEPY_MCP_PERSIST=0 to keep nothing on disk.

• MOVIEPY_MCP_MAX_CLIPS (default 48) drops the oldest clip that nothing else still uses. MOVIEPY_MCP_MAX_WIDTH, MAX_HEIGHT, and MAX_DURATION reject oversized media.

• download_video will not read browser cookies unless MOVIEPY_MCP_ALLOW_BROWSER_COOKIES=1.

• file_manager opens a drop zone in the chat. After upload, list_files returns each clip_id. download_media opens a player and download button for the finished clip; export_clip still writes a path you choose.

• 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