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 许可证。