Skip to main content
Glama
oktaycosar

manim-mcp

by oktaycosar
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

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

Circle to Square

Rotating Cube

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 <render_id> "Make the vectors red and add axis labels"

List, inspect, delete renders

manim-mcp list --status completed --limit 10
manim-mcp get <render_id>
manim-mcp delete <render_id> --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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oktaycosar/manim-mcp-ai'

If you have feedback or need assistance with the MCP directory API, please join our Discord server