# Manim Mcp

> Text-to-video animation via Manim. Text → Code → Video. CLI, agent mode, and MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-paulnegz-manim-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paulnegz](https://agentstack.voostack.com/s/paulnegz)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [paulnegz](https://github.com/paulnegz)
- **Source:** https://github.com/paulnegz/manim-mcp

## Install

```sh
agentstack add mcp-paulnegz-manim-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# manim-mcp

Text-to-video animation powered by [manimgl](https://github.com/3b1b/manim) (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](https://www.youtube.com/playlist?list=PLYfSs9pitF8Or8_cjhUaXh_sTSuJqskGD)**

## 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](https://github.com/buger/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

```bash
pip install -e ".[rag]"
```

### Prerequisites

- Python 3.11+
- [manimgl](https://github.com/3b1b/manim) installed: `pip install manimgl`
- A [Google Gemini API key](https://ai.google.dev/) 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](https://github.com/buger/probe) for AST-aware code search (install via `cargo install probe-search`)

### Environment Variables

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

```bash
# 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

```bash
# 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

```bash
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

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

### List, inspect, delete renders

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

### Agent mode

Let the LLM interpret multi-step requests:

```bash
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:

```bash
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:

```bash
# 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):

```bash
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

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

### Testing Scripts

```bash
# 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](https://github.com/paulnegz)
- **Source:** [paulnegz/manim-mcp](https://github.com/paulnegz/manim-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-paulnegz-manim-mcp
- Seller: https://agentstack.voostack.com/s/paulnegz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.