Manim MCP

🚀 manim-mcp

manim-mcp 是一個由 manimgl（3Blue1Brown 的庫）和多智能體大語言模型（LLM）管道驅動的文本到視頻動畫工具。你只需描述想要看到的內容，就能得到渲染後的動畫。

它既可以作為 命令行工具 使用，也能作為 基於大語言模型的智能體 運行，還能作為 MCP 服務器 與 Claude 等 AI 助手集成。

🚀 快速開始

pip install -e ".[rag]"

前提條件

• Python 3.11 及以上版本
• 安裝 manimgl：pip install manimgl
• 設置 Google Gemini API 密鑰 為 MANIM_MCP_GEMINI_API_KEY
• 可選：ChromaDB（用於 RAG）、ffmpeg（用於音頻混合）、LaTeX（用於數學文本）、S3/MinIO（用於雲存儲）
• 可選：使用 Probe 進行 AST 感知代碼搜索（通過 cargo install probe-search 安裝）

環境變量

將 .env.example 複製為 .env 並填寫相應的值：

# 大語言模型提供商
MANIM_MCP_GEMINI_API_KEY=your-gemini-api-key
MANIM_MCP_GEMINI_MODEL=gemini-3-flash-preview  # 默認值

# 可選：Claude
# MANIM_MCP_LLM_PROVIDER=claude
# MANIM_MCP_CLAUDE_API_KEY=your-claude-api-key
# MANIM_MCP_CLAUDE_MODEL=claude-sonnet-4-20250514

# 可選：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 存儲（可選）
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 搜索（可選 - 用於 AST 感知代碼搜索）
# 以冒號分隔的場景示例搜索路徑
MANIM_MCP_PROBE_PATHS=/path/to/3b1b-videos:/path/to/manim-examples

✨ 主要特性

• 基於檢索增強生成（RAG）的代碼生成：利用 5300 多個索引文檔進行高質量代碼生成，包括：
  • 3140 個 3Blue1Brown 場景示例
  • 1652 個 manimgl API 簽名及精確參數
  • 101 個動畫模式模板（如黎曼和、變換、物理等）
  • 470 個庫文檔文件
  • 16 種以上常見錯誤模式
• Probe 集成：可選的基於 Probe 的 AST 感知語義代碼搜索，具備：
  • 基於 Tree-sitter 的代碼解析（理解 Python 結構）
  • 混合 BM25 + TF-IDF 排名以實現更好的關鍵詞匹配
  • 完整代碼塊提取（無截斷）
• 多動畫視頻：每個視頻使用 2 種以上動畫模式，確保專業品質
• 多智能體管道：包括概念分析、場景規劃、代碼生成和代碼審查
• 自學習功能：存儲錯誤模式和修復方案，實現持續改進
• 多提供商大語言模型支持：支持 Google Gemini、Anthropic Claude 和 DeepSeek
• 音頻旁白：並行音頻生成並自動同步，具體流程為：
  • 首先生成視頻代碼（無旁白約束）
  • 文本轉語音（TTS）與視頻渲染並行運行
  • 音頻自動調整節奏以匹配視頻時長
• 參數驗證：通過 API 簽名防止無效方法調用

💻 使用示例

生成動畫

# 簡單模式（默認） - 直接使用大語言模型生成
manim-mcp gen "Transform a blue circle into a red square"

# 高級模式 - 使用 RAG 的多智能體管道
manim-mcp gen "Visualize the central limit theorem" --mode advanced

# 指定質量和格式選項
manim-mcp gen "Animate eigenvectors" --quality high --format mp4

生成模式說明：

• --mode simple（默認）：直接使用大語言模型生成代碼，速度較快
• --mode advanced：使用多智能體管道（概念分析器 → 場景規劃器 → 代碼生成器 → 代碼審查器）並結合 RAG 檢索

生成帶音頻旁白的動畫

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

音頻採用 並行管道 實現自動同步，具體步驟如下：

1. 首先生成 Manim 代碼（以視頻為驅動）
2. 視頻渲染和 TTS 生成並行運行
3. 音頻自動調整節奏以匹配視頻時長
4. 音頻混合到最終視頻中

編輯現有動畫

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

列出、查看和刪除渲染結果

manim-mcp list --status completed --limit 10
manim-mcp get <render_id>
manim-mcp delete <render_id> --yes

智能體模式

讓大語言模型解釋多步驟請求：

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

MCP 服務器

啟動模型上下文協議（MCP）服務器，以便與 Claude、Cursor 或其他 MCP 客戶端集成：

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

RAG 索引

對所有知識源進行索引，以獲得最佳代碼生成質量：

# 檢查當前索引狀態
manim-mcp index status

# 索引 3b1b 視頻場景（3140 個場景）
manim-mcp index 3b1b-videos --path /path/to/3b1b/videos

# 索引 manimgl API 簽名（1652 個簽名）
manim-mcp index api

# 索引動畫模式（101 個模式）
manim-mcp index patterns

# 索引錯誤模式（16 種以上模式）
manim-mcp index errors

# 索引庫文檔（470 個文檔）
manim-mcp index manim-docs

# 清除集合
manim-mcp index clear patterns --yes

📚 詳細文檔

Docker 使用方法

使用 Docker 運行幷包含所有依賴項（ChromaDB、MinIO）：

export MANIM_MCP_GEMINI_API_KEY=your-api-key
docker compose up

此命令將啟動以下服務：

• 端口 8000 上的 MCP 服務器
• 端口 8001 上的 ChromaDB
• 端口 9000/9001 上的 MinIO

架構說明

┌─────────────────────────────────────────────────────────────────────────────┐
│                      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)   │                     │
│   └───────────┘                       └───────────────┘                     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

組件說明

RAG 集合說明

自學習機制

系統會從每個錯誤中學習，具體方式如下：

1. 驗證失敗：當大語言模型糾正錯誤時，存儲修復方案
2. 渲染失敗：存儲失敗信息以便未來進行模式匹配
3. 成功修復：將錯誤→修復對存儲起來，用於 RAG 檢索

通過這種反饋循環，系統會隨著時間不斷改進。

MCP 工具說明

當作為 MCP 服務器運行時，可使用以下工具：

推薦提示

系統在具有高 RAG 覆蓋率的數學和教育主題上表現最佳：

開發說明

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

測試腳本

# 測試所有大語言模型提供商組合（Gemini/Claude × 簡單/高級 × RAG 開啟/關閉）
python scripts/test_providers.py
python scripts/test_providers.py --no-audio  # 跳過音頻生成
python scripts/test_providers.py --quick     # 僅進行簡單模式測試

# 對大語言模型提供商進行基準測試（DeepSeek 與 Gemini）
python scripts/benchmark_providers.py
python scripts/benchmark_providers.py --providers gemini,deepseek --categories simple,medium

📄 許可證

本項目採用 MIT 許可證。