JinDaGe - manim-mcp MCP Details

article

README

🚀 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

音频采用 并行管道 实现自动同步，具体步骤如下：

首先生成 Manim 代码（以视频为驱动）
视频渲染和 TTS 生成并行运行
音频自动调整节奏以匹配视频时长
音频混合到最终视频中

编辑现有动画

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

组件说明

| 组件 | 描述 | |-----------|-------------| | ConceptAnalyzer | 从提示中提取领域、复杂度和关键概念 | | ScenePlanner | 设计动画结构、时间安排和过渡效果 | | CodeGenerator | 使用场景、API 签名和动画模式生成 manimgl 代码 | | CodeReviewer | 验证代码质量并应用修复 | | ParameterValidator | 根据 API 签名验证方法参数 | | GeminiTTSService | 使用 Gemini 语音进行并行 TTS，生成旁白脚本 | | ChromaDBService | 对 5300 多个索引文档进行向量相似度搜索 | | ProbeSearcher | 使用 Probe（Tree-sitter + BM25）进行 AST 感知语义代码搜索 | | Linter | 使用 ruff 进行预生成代码验证 | | SelfCritique | 多轮代码生成并进行自我审查 | | SchemaGenerator | 基于 JSON 模式的结构化场景生成 | | TemplateGenerator | 模板优先的生成方式（填空式） | | CodeSandbox | 基于 AST 的安全验证（阻止危险代码） | | ManimRenderer | 使用 xvfb 执行 manimgl 进行无头渲染 | | S3Storage | 使用预签名 URL 上传到 MinIO/S3 | | RenderTracker | 将作业元数据持久化到 SQLite 中 |

RAG 集合说明

| 集合 | 文档数量 | 描述 | |------------|-----------|-------------| | manim_scenes | 3140 | 3Blue1Brown 生产环境场景代码 | | manim_api | 1652 | 包含精确参数的 API 签名 | | animation_patterns | 101 | 可复用的动画模板 | | manim_docs | 470 | manimgl 库文档 | | error_patterns | 16+ | 自学习的错误/修复模式 |

自学习机制

系统会从每个错误中学习，具体方式如下：

验证失败：当大语言模型纠正错误时，存储修复方案
渲染失败：存储失败信息以便未来进行模式匹配
成功修复：将错误→修复对存储起来，用于 RAG 检索

通过这种反馈循环，系统会随着时间不断改进。

MCP 工具说明

当作为 MCP 服务器运行时，可使用以下工具： | 工具 | 描述 | |------|-------------| | generate_animation | 根据文本提示创建动画 | | edit_animation | 根据指令编辑现有动画 | | list_renders | 分页和过滤列出过去的渲染结果 | | get_render | 获取完整详细信息和新的下载 URL | | delete_render | 永久删除渲染结果及其文件 | | rag_search | 在 RAG 数据库中搜索相似场景 | | rag_stats | 获取集合统计信息 |

开发说明

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

manim-mcp