<div align="center">

manim-server

FastAPI + MCP server for trusted Manim script rendering. (uses Manim Community) <video src="https://github.com/user-attachments/assets/9be7e5de-c89a-4c5a-9b6e-2852ae104acf" controls="controls" muted="muted" class="d-block rounded-bottom-2 border-top width-fit" style="max-height:480px; min-height: 200px"> </video> </div>

Install

uv sync --all-groups

Configure

Create .env from the example:

cp .env.example .env

Supported keys:

HOST=127.0.0.1
PORT=8000
DATA_DIR=.manim-server-data
TEMPLATE_DIR=template
MANIM_CLI_FLAGS=-ql
MANIM_TIMEOUT_SECONDS=120

Notes:

• DATA_DIR stores session JSON logs and rendered MP4 artifacts.
• TEMPLATE_DIR stores named full-wrapper Manim templates.
• MANIM_CLI_FLAGS is split like a shell command, then passed as subprocess args. Common values: -ql, -qm, -qh, -ql --fps 30.
• --save_sections, --media_dir, cache flags, scene path, and scene class are managed by the server.

Run

make run

Default server: http://127.0.0.1:8000.

Docker

Build the image:

make docker-build

Run it on http://127.0.0.1:8000:

make docker-run

Smoke-test the image:

make docker-smoke

The image is based on manimcommunity/manim:v0.20.1, matching the locked Manim dependency. That base image provides the Manim CLI plus common native rendering dependencies such as ffmpeg, Cairo/Pango, fonts, and minimal TeX Live. If a scene needs an extra TeX package, extend the image with that specific package instead of preinstalling all of TeX Live.

REST flow

The example builds one session from five Manim snippets, renders the final scene, then downloads the MP4. Use Manim-Session-ID when you want a stable id; omit it to let the server generate one.

# POST /sessions creates a new scene session.
# Response includes sessionId, title, sectionCount, and an empty section log.
curl -sS -X POST http://127.0.0.1:8000/sessions \
  -H 'content-type: application/json' \
  -H 'Manim-Session-ID: five-section-demo' \
  -d '{"title":"Five animated sections curl smoke"}'

# POST /sessions/<sessionId>/section appends one Manim code section.
# render=false records code without invoking Manim; cache is ignored until rendering.
curl -sS -X POST http://127.0.0.1:8000/sessions/five-section-demo/section \
  -H 'content-type: application/json' \
  -d '{"title":"Create blue circle","code":"circle = Circle(color=BLUE)\nself.play(Create(circle), run_time=1.0)","render":false}'

# Another section. Sections run in append order inside the generated scene.
curl -sS -X POST http://127.0.0.1:8000/sessions/five-section-demo/section \
  -H 'content-type: application/json' \
  -d '{"title":"Create green square","code":"square = Square(color=GREEN).shift(RIGHT * 2)\nself.play(Create(square), run_time=1.0)","render":false}'

# Adds a third shape, still only updating the session JSON log.
curl -sS -X POST http://127.0.0.1:8000/sessions/five-section-demo/section \
  -H 'content-type: application/json' \
  -d '{"title":"Create yellow triangle","code":"triangle = Triangle(color=YELLOW).shift(LEFT * 2)\nself.play(Create(triangle), run_time=1.0)","render":false}'

# Adds a fourth animation section.
curl -sS -X POST http://127.0.0.1:8000/sessions/five-section-demo/section \
  -H 'content-type: application/json' \
  -d '{"title":"Create lower line","code":"line = Line(LEFT, RIGHT, color=RED).shift(DOWN * 1.5)\nself.play(Create(line), run_time=1.0)","render":false}'

# Final section render=true appends code and runs Manim. cache defaults to "use",
# so omitting it lets Manim reuse existing cached partial movie files.
curl -sS -X POST http://127.0.0.1:8000/sessions/five-section-demo/section \
  -H 'content-type: application/json' \
  -d '{"title":"Create purple ellipse","code":"ellipse = Ellipse(width=3, height=1.5, color=PURPLE).shift(UP * 1.5)\nself.play(Create(ellipse), run_time=1.0)\nself.wait(0.1)","render":true}'

# GET /sessions/<sessionId>/video downloads the full MP4 from the latest render.
curl -sS -o /tmp/five-sections-full.mp4 \
  -w 'status=%{http_code} content_type=%{content_type} bytes=%{size_download}\n' \
  http://127.0.0.1:8000/sessions/five-section-demo/video

Open returned latestRender.fullVideoUrl, or a section URL such as /sessions/five-section-demo/sections/0001/video, in a browser or video client.

Cache modes for append_section with render=true, and for render_scene:

• Omit cache, or set "cache":"use": default; let Manim reuse cache.
• "cache":"flush": delete Manim partial movie cache before rendering.
• "cache":"disable": pass --disable_caching to Manim for that render.

Session templates

POST /sessions accepts optional templateId:

curl -sS -X POST http://127.0.0.1:8000/sessions \
  -H 'content-type: application/json' \
  -d '{"title":"Lecture","templateId":"lecture"}'

Template assets are Python files under TEMPLATE_DIR/<templateId>.py. By default this is ./template/<templateId>.py. Unknown missing templates fall back to default.py; if default.py is absent, session creation fails until the template directory is fixed.

Bundled templates:

• default: plain title header.
• clean-title: title header with underline.
• dark-grid: dark background with faint coordinate grid.
• presentation-card: animated title card intro, then clears before sections.

Template files are full Manim scripts, not scene-body snippets. Keep the scene class named GeneratedScene; Manim renders that class, and user sections are appended at EOF at the construct() body indentation. Do not put dedented code after construct() that would close that append point.

The reserved string literals "__SESSION_ID__", "__SESSION_TITLE__", and "__TEMPLATE_ID__" are replaced before render. Include them where the template needs those values:

from manim import *
from manim.opengl import *


class GeneratedScene(Scene):
    def construct(self):
        # DO NOT EDIT: replaced by manim-server before render.
        session_id = "__SESSION_ID__"
        session_title = "__SESSION_TITLE__"
        template_id = "__TEMPLATE_ID__"

        title = Text(session_title or "Untitled").to_edge(UP)
        self.add(title)

        # user sections append here

MCP endpoint

http://127.0.0.1:8000/mcp

Tools mirror REST: create_session, list_sessions, get_session, close_session, append_section, render_scene, reset_session.

Thanks

Special thanks to the Manim Community and 3Blue1Brown for their amazing work and inspiration.

Security

Scene code is trusted Python. Do not expose this server to untrusted users or networks.