manimgx-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@manimgx-mcp-server Create a 9:16 project and render a preview of scene 1."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
manimgx-mcp-server
An open-source, self-hostable MCP server for generating short technical animation clips with ManimGX. An MCP client plans a storyboard, writes ManimGX scenes, lints and inspects them, renders previews, collects approvals, renders final clips, and stitches an export.
ManimGX is not ManimCE. Do not install or import
manim. Scenes useimport manimgx as m. Typesetting is Typst only — no LaTeX installation is required.
Features
Fast previews at 480×854, 15 fps
Final renders at 1080×1920, 60 fps
Single-process batch rendering — one ManimGX import and GPU initialization for a whole storyboard
Typst-only scenes with no LaTeX dependency
Deterministic AST linting before code execution
Layout inspection with structured problem reports and storyboard frames
Bounded review state machine with rejection reasons
SQLite persistence that survives restarts and stateless MCP connections
Stitching, frame extraction, and mpv previews
Strict path handling — project/scene IDs cannot traverse directories or follow symlinks out of the project
All milestones in PLAN.md are implemented.
Related MCP server: ai-video-studio-agent
Requirements
Python 3.13–3.14
Vulkan-capable GPU, or Mesa lavapipe for CPU fallback (ManimGX bundles a lavapipe fallback)
ffmpegandffprobefor stitching and frame extractionmpvoptionally, for desktop previews
On Arch Linux:
sudo pacman -S --needed uv mpv ffmpeg git base-devel \
vulkan-icd-loader vulkan-headers vulkan-tools mesaOn Debian/Ubuntu:
curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt-get install -y ffmpeg libvulkan1 mesa-vulkan-driversDo not install texlive, texlive-most, or the typst CLI. ManimGX includes
fonts, Typst, and MP4 encoding.
Install and run
From a published package
uvx manimgx-mcp-serverThe package exposes both manimgx-mcp-server and manimgx-mcp commands.
From a local wheel
uv build
uvx --from dist/*.whl manimgx-mcpFrom source
git clone https://github.com/scharanruka/manimgx-mcp-server.git
cd manimgx-mcp-server
uv sync
uv run manimgx-mcpVerify the environment:
uv run manimgx --version
uv run python scripts/check_connection.pyThe connection script starts the real server over stdio, lists every tool,
prompt, and resource template, then creates a temporary project. Expected output
ends with Connection test passed.
MCP client configuration
Recommended, using uvx:
{
"mcpServers": {
"manimgx": {
"command": "uvx",
"args": ["manimgx-mcp-server"]
}
}
}Local development:
{
"mcpServers": {
"manimgx": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/manimgx-mcp-server",
"manimgx-mcp"
]
}
}
}The server speaks MCP over stdio. Logs go to stderr; stdout is reserved for the protocol.
Quick workflow
project_start(brief) # asks for aspect ratio + clip count if missing
→ storyboard_save(beats) # no durations: the beats decide the length
→ project_build(code) # lint + render + stitch + bundle, one call
→ { video.mp4, code.py, storyboard.json, report.json }project_build splits a combined code.py into scene files, lints all of them,
renders only the scenes whose code changed in one worker process, stitches the
final video, writes the bundle, and deletes previews, frames and scratch files.
Pass review=true to stop after previews, and inspect=true for layout checks.
Editing is the same call: pass the edited code.py back to project_build.
The lower-level tools (scene_write, scene_lint, scene_render_preview,
scene_review, project_stitch, …) remain available for debugging and manual
control.
Tools
Tool | Description |
| Create a project from a brief, eliciting missing format parameters. |
| Lint, render, stitch, and bundle a project in one call. |
| Return the finished bundle without rebuilding. |
| Create a project with a 9:16 or 16:9 config. |
| Read config, paths, storyboard, scenes, and status counts. |
| Update validated colors, fonts, safe area, and render settings. |
| Validate a storyboard and create its planned scenes. |
| Write scene code and clear stale artifacts on change. |
| List scenes with status and code metadata. |
| Read one scene's plan, code, and artifacts. |
| Run deterministic AST checks without executing code. |
| Check layout at the project's frame size without video (opt-in). |
| Render a 480p15 preview and return its report. |
| Render many preview or final clips in one worker. |
| Render a 1080p60 final; requires approval or |
| Approve or reject a previewed scene with a reason. |
| Concatenate final clips into one exported MP4. |
| Extract PNG review frames at requested times. |
| Open a preview or final video in detached mpv. |
MCP resources
Resources are cheaper than tools for reading context on demand.
URI | Returns |
| Project config JSON |
| Storyboard JSON |
| Scene Python code |
| Last lint/inspect/render reports |
MCP prompts
The server does not call an LLM. Prompts tell the host client which model to use and provide a compact, stable context. They never include chat history.
Prompt | Model hint | Purpose |
| DeepSeek Pro | Produce Storyboard JSON only |
| DeepSeek Flash | Produce one complete ManimGX scene file |
| DeepSeek Flash | Repair a rejected scene from structured errors |
scene_edit_prompt sends the scene plan, config, current code (or an AST skeleton
when the file exceeds 80 lines), lint issues, inspect issues, and the rejection
reason.
Storage
Working projects live under MANIM_MCP_HOME (default ~/.manimgx-mcp/projects).
Projects created by project_start are ephemeral: their directory is deleted when
the MCP session disconnects. The finished bundle is copied to
MANIM_MCP_EXPORT_HOME (default ~/.manimgx-mcp/exports/<project_id>/) and kept
for MANIM_MCP_EXPORT_TTL_DAYS days (default 7).
<MANIM_MCP_HOME>/<project_id>/
├── project.db
├── scenes/
├── renders/
│ ├── preview/
│ ├── final/
│ └── storyboards/
├── frames/
├── exports/
└── logs/<MANIM_MCP_EXPORT_HOME>/<project_id>/
├── video.mp4
├── code.py
├── storyboard.json
└── report.jsonproject.db is the source of truth. It stores projects, scenes, artifacts, and an
append-only event log. Project IDs are a sanitized slug plus a short UUID suffix.
Project and scene IDs are validated as single path components; traversal,
absolute paths, and symlink escapes are rejected.
project_update_theme accepts only these keys:
{
"background_color": "BLACK",
"text_color": "WHITE",
"accent_color": "BLUE",
"font_sizes": {"title": 64, "body": 32, "caption": 24},
"safe_area": {"x_min": -4, "x_max": 4, "y_min": -7, "y_max": 7},
"preview_width": 480,
"preview_height": 854,
"preview_fps": 15,
"preview_preset": "ultrafast",
"preview_crf": 30,
"final_width": 1080,
"final_height": 1920,
"final_fps": 60,
"final_preset": "medium",
"final_crf": 18
}Partial updates are merged; nested font_sizes and safe_area also merge.
Rendering quality gates
storyboard_save requires 1–100 clips, each 1–30 seconds, with a total of 10–90
seconds. Scene IDs must be unique safe slugs.
scene_lint never executes scene code. It rejects:
Forbidden imports:
manim,os,sys,subprocess,socket,requests,urllib,pathlib,shutilForbidden calls:
open,eval,exec,compile,__import__,globals,locals,input,breakpointMissing or multiple scene classes
Missing or malformed
construct(self) -> NoneInfinite
while Truewithout a breakScenes over 200 lines or 45 estimated seconds
LaTeX typesetting in Typst projects
Missing
m.Typst/m.MathTypst
Safe-area coordinate problems are warnings, not failures. Reports are capped at 10 structured issues.
Performance
Measured on the development machine with ManimGX 0.1.1:
20 preview clips, 6.66s of video, 0.76s wall, 60s budget
final render: 1080×1920, H.264, 60 fpsBatch rendering imports ManimGX once, initializes the GPU once, and renders every
scene sequentially in one subprocess. It does not launch one manimgx process per
clip.
Run the benchmark:
uv run pytest tests/bench_batch.py -q -sSecurity
Generated scene code is untrusted.
Lint runs before execution; render workers run in subprocesses, never in the MCP server process.
Every render has a timeout, and the batch worker has an additional per-scene timeout.
Scene subprocesses run with the project directory as their working directory.
Project and scene IDs are validated before path joins.
Artifact paths are resolved back inside the project before deletion.
The server writes logs to stderr only.
For higher isolation, run the server inside a container or wrap the render worker
with bwrap on systems that provide it.
Development
uv sync
uv run ruff check .
uv run ruff format --check .
uv run pytestSkip the slow benchmark:
uv run pytest -m "not slow"Build and smoke-test the wheel:
uv build
uvx --from dist/*.whl manimgx-mcpSee CONTRIBUTING.md and AGENTS.md.
Releases
The release workflow runs on v* tags, builds the wheel and sdist, and publishes
them to PyPI through trusted publishing. Configure a PyPI trusted publisher for
the repository and the pypi GitHub environment before tagging.
Project layout
src/ flat server modules (no package subdirectory)
examples/scenes/ example ManimGX scene
scripts/ stdio connection smoke client
tests/ unit and integration tests
.github/workflows/ CI and release workflows
PLAN.md build specification and milestonesLicense
MIT
Available Tools
19 toolsproject_buildProject BuildC
Build scenes, stitch the video, and return clips plus code.py.
Inputs: project_id (required), code, force, review, +1 more. Returns: A built project: the video, the editable code, and the scene reports.
project_createProject CreateC
Create an animation project and return its paths and config.
Inputs: name (required), theme, aspect_ratio. Returns: Project config, paths, storyboard, scenes, and status counts.
project_exportProject ExportC
Return the finished bundle: video, code.py, storyboard, and report.
Inputs: project_id (required). Returns: A built project: the video, the editable code, and the scene reports.
project_getProject GetB
Get a project with config, storyboard, scenes, and status counts.
Inputs: project_id (required). Returns: Project config, paths, storyboard, scenes, and status counts.
project_render_batchProject Render BatchC
Render many scenes in one worker process.
Inputs: project_id (required), mode, scene_ids. Returns: Result of one batch worker process rendering many scenes.
project_startProject StartC
Start a project, asking the user for any missing format parameters.
Inputs: brief (required), style, theme, clip_count, +1 more. Returns: Result of starting an animation project.
project_stitchProject StitchC
Stitch final-rendered clips into one MP4.
Inputs: project_id (required), scene_ids, output_name. Returns: Result of stitching final clips into one MP4.
project_update_themeProject Update ThemeC
Update validated project theme and render settings.
Inputs: theme (required), project_id (required). Returns: Project config, paths, storyboard, scenes, and status counts.
scene_extract_framesScene Extract FramesC
Extract PNG review frames at requested times.
Inputs: times (required), scene_id (required), project_id (required). Returns: Result of extracting review frames from a rendered scene.
scene_getScene GetC
Get a scene's plan, code, status, and artifacts.
Inputs: scene_id (required), project_id (required). Returns: A scene with its full plan, source code, and code path.
scene_inspectScene InspectB
Inspect layout at preview frames without rendering video.
Inputs: scene_id (required), project_id (required), times. Returns: Result of running ManimGX inspect without rendering video.
scene_lintScene LintB
Lint scene code without executing it.
Inputs: scene_id (required), project_id (required). Returns: Compact scene lint result.
scene_listScene ListC
List scenes in storyboard order.
Inputs: project_id (required). Returns: result
scene_open_mpvScene Open MpvB
Open a rendered scene in a detached mpv window.
Inputs: scene_id (required), project_id (required), mode. Returns: Result of opening a rendered scene in mpv.
scene_render_finalScene Render FinalC
Render approved final video at 1080p60.
Inputs: scene_id (required), project_id (required), force. Returns: Result of rendering preview or final video.
scene_render_previewScene Render PreviewC
Render a 480p preview and return its report.
Inputs: scene_id (required), project_id (required). Returns: Result of rendering preview or final video.
scene_reviewScene ReviewC
Approve or reject a previewed scene.
Inputs: decision (required), scene_id (required), project_id (required), reason. Returns: Compact scene metadata for project listings.
scene_writeScene WriteB
Write scene source, reset its status, and clear stale artifacts.
Inputs: code (required), scene_id (required), project_id (required). Returns: Compact scene metadata for project listings.
storyboard_saveStoryboard SaveC
Validate and persist a storyboard and its planned scenes.
Inputs: project_id (required), storyboard (required). Returns: Validated storyboard produced by the host LLM.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools map to distinct project, storyboard, scene, or render operations. There is some overlap between project_start/project_create and among the rendering/stitching/export tools, but descriptions usually clarify the intended use.
All tools use a consistent snake_case resource_action pattern, with project_, storyboard_, and scene_ prefixes. Multi-word actions like render_final and extract_frames remain predictable.
Nineteen tools is somewhat heavy, but the animation pipeline legitimately spans project setup, storyboarding, scene authoring, previewing, review, rendering, stitching, and export. A few convenience tools could be consolidated, but most earn their place.
The surface covers the core lifecycle from project creation through scene writing, review, rendering, and final export. Minor gaps exist around deletion or cleanup of projects/scenes, but agents can work around them for the main workflow.
Related MCP Connectors
Hosted video MCP server for branded explainers and reference-driven edits.
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
Build editable 3D scenes, direct characters and cameras, and export AI video references with MCP.
Hosted MCP for Remotion videos: search Remocn components, read docs, plan a video, preview it.
Related MCP Servers
- AlicenseCqualityDmaintenanceExposes manimgl mathematical animation functionality as MCP tools, enabling LLMs to create animated scenes with narration and background music, and render to video.58MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides a local Web production console and HTTP control plane for AI video creation, exposing tools for project/revision management, media analysis, editing, review, and delivery while keeping formal rendering behind explicit approval gates.-
- AlicenseNot gradedqualityDmaintenanceEnables LLM agents to generate labeled contact sheets of Manim animations, scaffold storyboards from renders, and validate rendered steps against expected intents via MCP tools.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and MCP clients to run self-hosted video production workflows, including project planning, rendering, review, and delivery with durable background jobs and local review.2Apache 2.0