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.

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",
        "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")
fade(clip_id=..., fade_out_seconds=1.5)
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.

• 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.

License

MIT