Manim MCP
A Docker-based environment for creating mathematical animations with Manim, featuring both a CLI interface and a web API with Model Context Protocol (MCP) support for AI assistants.
📑 Overview
This project provides:
- Containerized Manim Environment: Run Manim in an isolated, reproducible Docker environment
- Web API: Create and manage Manim animations via HTTP requests
- MCP Integration: Direct interaction with AI assistants like Claude
- File Management: Upload scripts and download generated animations
🚀 Quick Start
Prerequisites
- Docker and Docker Compose installed on your system
Installation
Option 1: Use the Prebuilt Image (Recommended)
Simply pull the prebuilt image from Docker Hub:
docker pull wstcpyt/manim-docker-mcp:latest
Then run it with docker-compose:
docker compose up -d
Option 2: Build Locally
-
Clone the repository:
git clone https://github.com/YOUR_USERNAME/manim-docker-mcp.git cd manim-docker-mcp
-
Build the Docker images:
docker compose build
Usage
CLI Mode
Create a Python file in the animations directory (see example below), then run:
docker compose run manim -pql animations/example.py ExampleScene
API Mode
Start the API server:
docker compose up -d manim-api
Access the API documentation at http://localhost:8000/docs
🎬 Creating Animations
Basic Example
Create a file animations/example.py:
from manim import *
class CircleToSquare(Scene):
def construct(self):
circle = Circle()
circle.set_fill(BLUE, opacity=0.5)
square = Square()
square.set_fill(RED, opacity=0.5)
self.play(Create(circle))
self.wait()
self.play(Transform(circle, square))
self.wait()
Running the Animation
# CLI mode with preview (-p), low quality (-ql)
docker compose run manim -pql animations/example.py CircleToSquare
# API mode
curl -X POST "http://localhost:8000/run-manim?filepath=/manim/temp/circle_example.py&scene_name=CircleToSquare&quality=low_quality"
📂 Project Structure
manim-docker-mcp/
├── animations/ # Manim animation scripts
├── app/ # FastAPI application
├── media/ # Generated animations (CLI mode)
├── output/ # Generated animations (API mode)
├── temp/ # Temporary files
├── uploads/ # Uploaded animation scripts
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
└── README.md # This file
🔧 Configuration
Quality Settings
| Flag | Resolution | Frame Rate | Best For |
|---|---|---|---|
-ql |
480p | 15fps | Quick previews |
-qm |
720p | 30fps | General use |
-qh |
1080p | 60fps | Presentations |
-qk |
1440p | 60fps | Production videos |
Other Useful Flags
-p: Preview the output file-t: Transparent background--save_last_frame: Render only the last frame-c COLOR: Set background color
🌐 API Documentation
Core Endpoints
List Files
GET /list-files?directory=/manim
Write File
POST /write-file?filepath=/manim/temp/example.py
Run Animation
POST /run-manim?filepath=/manim/temp/example.py&scene_name=CircleToSquare
Download Animation
GET /download-file?filepath=/media/videos/example/480p15/CircleToSquare.mp4
Full API documentation is available at the /docs endpoint.
🤖 AI Assistant Integration (MCP)
This project supports the Model Context Protocol (MCP), enabling AI assistants to:
- Create Manim scripts based on natural language descriptions
- Run animations and provide download links
- Browse and manage generated media files
Example MCP session:
User: Create an animation showing a circle morphing into a square
AI: I'll create that for you...
🔍 Advanced Usage
Custom LaTeX
The container includes a minimal LaTeX installation. Custom LaTeX can be used in animations:
formula = MathTex(r"\int_{a}^{b} f(x) \, dx = F(b) - F(a)")
self.play(Write(formula))
Mounting Custom Directories
Modify the docker-compose.yml file to mount additional directories:
volumes:
- ./my_custom_dir:/manim/custom
🛠️ Troubleshooting
Common Issues
- Docker not running: Make sure Docker daemon is running
- Permission errors: The container needs write access to mounted volumes
- Missing media: Check the correct output directory (media/ for CLI, output/ for API)
Getting Help
If you encounter issues:
- Check the Manim documentation
- Search existing GitHub issues
- Create a new issue with details about your problem
📜 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
🙏 Acknowledgements
- Manim Community for the amazing animation engine
- FastAPI for the web framework
- Model Context Protocol for AI integration
Metadata
Release files for iflow-mcp-wstcpyt-manim-mcp 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_wstcpyt_manim_mcp-0.1.2.tar.gz | 16.9 kB | Without provenance | Details for iflow_mcp_wstcpyt_manim_mcp-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_wstcpyt_manim_mcp-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_wstcpyt_manim_mcp-0.1.2-py3-none-any.whl |
Total release size: 32.2 kB
Release files / iflow_mcp_wstcpyt_manim_mcp-0.1.2.tar.gz
| Download URL | iflow_mcp_wstcpyt_manim_mcp-0.1.2.tar.gz |
|---|---|
| Size | 16.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5885fca4390872e4f0ce3421a7514eddf2ea8b17c3d15ce4123744098c6e04df
|
|
BLAKE2b-256 checksum How to use checksums |
18b91a7e0565c88f2c41eb9b8771f7d6649935b899c0585903ca6d32340002d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_wstcpyt_manim_mcp-0.1.2-py3-none-any.whl
| Download URL | iflow_mcp_wstcpyt_manim_mcp-0.1.2-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7b9ad4495452d14568dca36b37a5e3c9809048a5b02229f7a30cac0a432a87e
|
|
BLAKE2b-256 checksum How to use checksums |
692694ad2e26a38ee6b36f1e02a7dd5dda8c4413ea401531b7298e766f177645
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp-wstcpyt-manim-mcp 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.