Manim Mcp

manim-mcp

Text-to-video animation powered by manimgl (3Blue1Brown's library) and a multi-agent LLM pipeline. Describe what you want to see, and get a rendered animation back.

Works as a CLI tool, an LLM-powered agent, or an MCP server for integration with AI assistants like Claude.

Examples

| Circle to Square Transform | 3D Rotating Cube | |---------------------------|------------------| | manim-mcp gen "Transform a blue circle into a red square" | manim-mcp gen "A 3D cube rotating. Use ThreeDScene." | | | |

Watch 20+ example animations on YouTube

Features

• RAG-powered code generation - Uses 5,300+ indexed documents for high-quality code generation:
• 3,140 3Blue1Brown scene examples
• 1,652 manimgl API signatures with exact parameters
• 101 animation pattern templates (Riemann sums, transforms, physics, etc.)
• 470 library documentation files
• 16+ error patterns for common mistakes
• Probe integration - Optional AST-aware semantic code search using Probe:
• Tree-sitter based code parsing (understands Python structure)
• Hybrid BM25 + TF-IDF ranking for better keyword matching
• Complete code block extraction (no truncation)
• Multi-animation videos - Each video uses 2+ animation patterns for professional quality
• Multi-agent pipeline - Concept analysis, scene planning, code generation, and code review
• Self-learning - Stores error patterns and fixes for continuous improvement
• Multi-provider LLM - Supports Google Gemini, Anthropic Claude, and DeepSeek
• Audio narration - Parallel audio generation with automatic sync:
• Video code generated first (no narration constraint)
• TTS runs in parallel with video rendering
• Audio automatically paced to match video duration
• Parameter validation - API signatures prevent invalid method calls

Quick Start

pip install -e ".[rag]"

Prerequisites

• Python 3.11+
• manimgl installed: pip install manimgl
• A Google Gemini API key set as MANIM_MCP_GEMINI_API_KEY
• Optional: ChromaDB (for RAG), ffmpeg (for audio mixing), LaTeX (for math text), S3/MinIO (for cloud storage)
• Optional: Probe for AST-aware code search (install via cargo install probe-search)

Environment Variables

Copy .env.example to .env and fill in your values:

# LLM Provider
MANIM_MCP_GEMINI_API_KEY=your-gemini-api-key
MANIM_MCP_GEMINI_MODEL=gemini-3-flash-preview  # default

# Alternative: Claude
# MANIM_MCP_LLM_PROVIDER=claude
# MANIM_MCP_CLAUDE_API_KEY=your-claude-api-key
# MANIM_MCP_CLAUDE_MODEL=claude-sonnet-4-20250514

# Alternative: DeepSeek
# MANIM_MCP_LLM_PROVIDER=deepseek
# MANIM_MCP_DEEPSEEK_API_KEY=your-deepseek-api-key

# RAG (ChromaDB)
MANIM_MCP_RAG_ENABLED=true
MANIM_MCP_CHROMADB_HOST=localhost
MANIM_MCP_CHROMADB_PORT=8000

# S3 Storage (optional)
MANIM_MCP_S3_ENDPOINT=localhost:9000
MANIM_MCP_S3_ACCESS_KEY=minioadmin
MANIM_MCP_S3_SECRET_KEY=minioadmin
MANIM_MCP_S3_BUCKET=manim-renders

# Probe Search (optional - for AST-aware code search)
# Colon-separated paths to search for scene examples
MANIM_MCP_PROBE_PATHS=/path/to/3b1b-videos:/path/to/manim-examples

Usage

Generate an animation

# Simple mode (default) - direct LLM generation
manim-mcp gen "Transform a blue circle into a red square"

# Advanced mode - multi-agent pipeline with RAG
manim-mcp gen "Visualize the central limit theorem" --mode advanced

# With quality and format options
manim-mcp gen "Animate eigenvectors" --quality high --format mp4

Generation modes:

• --mode simple (default): Direct LLM code generation, faster
• --mode advanced: Multi-agent pipeline (ConceptAnalyzer → ScenePlanner → CodeGenerator → CodeReviewer) with RAG retrieval

Generate with audio narration

manim-mcp gen "Introduction to linear algebra" --audio
manim-mcp gen "Pythagorean theorem proof" --audio --voice Kore

Audio uses a parallel pipeline with automatic sync:

1. Manim code is generated first (video-driven)
2. Video rendering and TTS generation run in parallel
3. Audio is automatically paced to match video duration
4. Audio is mixed into the final video

Edit an existing animation

manim-mcp edit  "Make the vectors red and add axis labels"

List, inspect, delete renders

manim-mcp list --status completed --limit 10
manim-mcp get 
manim-mcp delete  --yes

Agent mode

Let the LLM interpret multi-step requests:

manim-mcp prompt "Create a video on eigenvectors, then edit it with better colors"

MCP server

Start the Model Context Protocol server for integration with Claude, Cursor, or other MCP clients:

manim-mcp serve
manim-mcp serve --transport stdio
manim-mcp serve --transport streamable-http

RAG Indexing

Index all knowledge sources for best code generation quality:

# Check current index status
manim-mcp index status

# Index 3b1b video scenes (3,140 scenes)
manim-mcp index 3b1b-videos --path /path/to/3b1b/videos

# Index manimgl API signatures (1,652 signatures)
manim-mcp index api

# Index animation patterns (101 patterns)
manim-mcp index patterns

# Index error patterns (16+ patterns)
manim-mcp index errors

# Index library documentation (470 docs)
manim-mcp index manim-docs

# Clear a collection
manim-mcp index clear patterns --yes

Docker

Run with all dependencies (ChromaDB, MinIO):

export MANIM_MCP_GEMINI_API_KEY=your-api-key
docker compose up

This starts:

• MCP server on port 8000
• ChromaDB on port 8001
• MinIO on ports 9000/9001

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      AUDIO PIPELINE (parallel with video)                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   prompt ──► Code Generation (video-driven)                                  │
│                           │                                                  │
│              ┌────────────┴────────────┐                                     │
│              │                         │  PARALLEL                           │
│              ▼                         ▼                                     │
│   ┌──────────────────┐      ┌──────────────────┐                            │
│   │  Render Video    │      │  Generate Script │                            │
│   │                  │      │  + TTS Audio     │                            │
│   └────────┬─────────┘      └────────┬─────────┘                            │
│            │                         │                                       │
│            ▼                         ▼                                       │
│       video.mp4              audio segments                                  │
│            │                         │                                       │
│            └────────────┬────────────┘                                       │
│                         ▼                                                    │
│              Pace audio to video duration                                    │
│                         │                                                    │
│                         ▼                                                    │
│                  Mix Audio + Video ──► S3 upload ──► URL                     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MULTI-AGENT PIPELINE                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   prompt ──► ConceptAnalyzer ──► ScenePlanner ──► CodeGenerator ──► CodeReviewer
│                    │                   │                │                │   │
│                    ▼                   ▼                ▼                ▼   │
│              ┌─────────────────────────────────────────────────────────┐     │
│              │                    ChromaDB RAG (5,300+ docs)           │     │
│              │  ┌──────────┬──────────┬──────────┬────────┬────────┐  │     │
│              │  │  scenes  │   api    │ patterns │  docs  │ errors │  │     │
│              │  │  (3,140) │ (1,652)  │  (101)   │ (470)  │  (16)  │  │     │
│              │  └──────────┴──────────┴──────────┴────────┴────────┘  │     │
│              └─────────────────────────────────────────────────────────┘     │
│                                                                              │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            RENDER PIPELINE                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   validated code ──► CodeSandbox ──► manimgl (xvfb) ──► S3 upload ──► URL   │
│         │                                    │                               │
│         ▼                                    ▼                               │
│   ┌───────────┐                       ┌───────────────┐                     │
│   │  SQLite   │                       │    MinIO/S3   │                     │
│   │ (tracker) │                       │   (storage)   │                     │
│   └───────────┘                       └───────────────┘                     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Components

| Component | Description | |-----------|-------------| | ConceptAnalyzer | Extracts domain, complexity, and key concepts from prompts | | ScenePlanner | Designs animation structure, timing, and transitions | | CodeGenerator | Generates manimgl code using scenes, API signatures, and animation patterns | | CodeReviewer | Validates code quality and applies fixes | | ParameterValidator | Validates method parameters against API signatures | | GeminiTTSService | Parallel TTS with Gemini voices, generates narration script | | ChromaDBService | Vector similarity search across 5,300+ indexed documents | | ProbeSearcher | AST-aware semantic code search using Probe (tree-sitter + BM25) | | Linter | Pre-generation code validation using ruff | | SelfCritique | Multi-pass code generation with self-review | | SchemaGenerator | JSON schema-based structured scene generation | | TemplateGenerator | Template-first generation (fill-in-the-middle style) | | CodeSandbox | AST-based security validation (blocks dangerous code) | | ManimRenderer | Executes manimgl with xvfb for headless rendering | | S3Storage | Uploads to MinIO/S3 with presigned URLs | | RenderTracker | Persists job metadata in SQLite |

RAG Collections

| Collection | Documents | Description | |------------|-----------|-------------| | manim_scenes | 3,140 | Production 3Blue1Brown scene code | | manim_api | 1,652 | API signatures with exact parameters | | animation_patterns | 101 | Reusable animation templates | | manim_docs | 470 | manimgl library documentation | | error_patterns | 16+ | Self-learning error/fix patterns |

Self-Learning

The system learns from every error:

1. Validation failures - Stored with fixes when LLM corrects them
2. Render failures - Stored for future pattern matching
3. Successful fixes - Stored as error→fix pairs for RAG retrieval

This creates a feedback loop where the system improves over time.

MCP Tools

When running as an MCP server, these tools are available:

| Tool | Description | |------|-------------| | generate_animation | Create an animation from a text prompt | | edit_animation | Edit an existing animation with instructions | | list_renders | List past renders with pagination and filtering | | get_render | Get full details and a fresh download URL | | delete_render | Permanently delete a render and its files | | rag_search | Search the RAG database for similar scenes | | rag_stats | Get collection statistics |

Recommended Prompts

The system performs best with mathematical and educational topics that have high RAG coverage:

| Topic | Indexed Scenes | Example Prompts | |-------|----------------|-----------------| | Linear Algebra | 810+ | "Animate a matrix transformation", "Show eigenvectors during transformation" | | Geometry | 568+ | "Visual proof of Pythagorean theorem", "Inscribed angle theorem" | | Probability | 290+ | "Central limit theorem", "Bayes theorem with updating priors" | | Calculus | 178+ | "Derivative as tangent slope", "Riemann sums converging to integral" |

Development

pip install -e ".[dev,rag]"
pytest

Testing Scripts

# Test all LLM provider combinations (Gemini/Claude × Simple/Advanced × RAG On/Off)
python scripts/test_providers.py
python scripts/test_providers.py --no-audio  # Skip audio generation
python scripts/test_providers.py --quick     # Only simple mode tests

# Benchmark LLM providers (DeepSeek vs Gemini)
python scripts/benchmark_providers.py
python scripts/benchmark_providers.py --providers gemini,deepseek --categories simple,medium

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: paulnegz
• Source: paulnegz/manim-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.