Math Animation

一句话描述你想要的动画，AI 自动生成 3Blue1Brown 风格教学视频

支持：文字描述 / LaTeX 公式 / PDF 试卷 / 图片截图 → 自动输出教学 MP4
覆盖：高考/中考数学、物理、计算机科学，零编程基础可用

Python 3.11+ Manim MCP License: MIT

---

📺 效果展示

下面是本项目已渲染的真实案例（全部代码见 examples/ 目录）：

🏆 2025 高考真题讲解（3 道大题）

题目	时长	内容亮点
第17题 立体几何	1分13秒	四棱锥3D建模 + 360°旋转 + 球面可视化 + 二面角计算
第18题 圆锥曲线	1分32秒	椭圆逐步求解 + 动点轨迹动画 +
第19题 导数压轴	2分05秒	f(x)=5cosx−cos5x 全解 + 和差化积可视化 + φ 扫描动画

📚 基础数学 15 个案例

案例	时长	知识点
欧拉公式	~20s	$e^{i\pi}+1=0$，复平面旋转动画
配方法	~15s	逐步配方 + 抛物线图像
三角函数变换	~15s	A/ω/φ 逐步变化对比
向量加法	~12s	平行四边形法则
ε-δ 极限定义	~15s	可视化 ε 带和 δ 带
矩阵乘法	~15s	逐元素展开
泰勒展开	~18s	7 阶逼近 sin(x)
贝叶斯定理	~20s	韦恩图 + 医学检测案例
斐波那契/黄金比例	~18s	比值趋近 φ 的折线图
复数平面	~15s	复数运算几何意义
杨辉三角	~12s	逐行生成 + 二项式定理
排序算法	~14s	时间复杂度对比表
微积分基本定理	~20s	面积可视化
简谐运动	~18s	弹簧动画 + 实时波形描绘
3D 空间平面	~35s	三维旋转 + 法向量

🔬 进阶长案例 12 个

案例	时长	知识点
高考导数压轴	45s	f(x)=x−1−a·ln(x)，单调性讨论+不等式证明
3D 立体几何	30s	正方体截面 + 二面角计算
高考含参函数	42s	f(x)=eˣ−ax−1，含参讨论 + 极值
高考递推数列	40s	取倒数化等差 + 前 8 项验证
抛体运动	32s	轨迹 + 实时速度矢量 + 三角度对比
电场力与电势	32s	电场线 + 等势面 + 电偶极子
椭圆焦点性质	30s	动点绕行，实时验证
弹簧能量守恒	32s	Ek/Ep 时间曲线 + 相空间椭圆
直线与圆	37s	相交/相切/相离三种情况
SIR 传染病模型	25s	微分方程数值解 + 群体免疫阈值
法拉第定律	30s	滑轨动画 + EMF 推导
特征值与特征向量	40s	矩阵变换 + 网格变形动画

💻 力扣算法可视化 3 个（图形为主）

设计原则：图形占画面 80%+，指针/节点/队列全程动态可见，文字只作小标签

案例	时长	代码	内容亮点
#1 Two Sum	33s	O(n²) → O(n) 对比	数组方块高亮 + 暴力双循环 + HashMap 构建动画 + 补数查找连线
#206 反转链表	46s	迭代三指针	5节点链表 + prev/curr/next 指针逐步移动 + 箭头翻转动画 + 节点变色
#102 层序遍历	32s	BFS + 队列	7节点二叉树 + 队列入队出队动画 + 层级颜色区分 + 父子连线

🏆 2024 高考真题讲解（图形为主，3 道大题）

新版设计：图形始终占满画面，文字标签随图形变化，全程无大段文字推导

题目	时长	代码	内容亮点
第16题 解析几何(椭圆)	51s	x²/4+y²/3=1	椭圆描点轨迹 + 焦弦连续扫描 + 三角形面积实时计算 +
第17题 立体几何	53s	正三棱柱 + 圆	棱柱3D构建 + 半圆弧D点运动 + Thales定理直角 + 法向量计算 + 360°旋转
第18题 导数函数	71s	f(x)=eˣ−ax−1	切线连续扫描 + 单调区间着色 + f(x)≥0证明 + 参数a扫描曲线族

---

🚀 30 秒快速开始

方式 A：Docker（零基础首选，5 分钟内出效果）

# 克隆项目
git clone https://github.com/bcefghj/math-animation-mcp.git
cd math-animation-mcp

# 一键启动（自动下载依赖）
docker compose up -d

# 打开浏览器
# → http://localhost:7860

方式 B：Cursor MCP（程序员推荐）

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "math-animation": {
      "command": "uvx",
      "args": ["math-animation-mcp"],
      "env": { "OUTPUT_DIR": "./animation_output" }
    }
  }
}

重启 Cursor，Cmd+L 打开对话直接说话：

帮我做一个勾股定理证明动画，适合初中生
@高考数学.pdf 讲解第18题
把这段导数知识点做成动画，黑板风格

方式 C：pip 安装

pip install math-animation-mcp
math-animation-mcp --web       # 启动 Web 界面
# → http://localhost:7860

---

📖 保姆级安装教程

完全小白也能看懂，按步骤来，10 分钟搞定

第一步：确认你的电脑系统

• 苹果 Mac（macOS）→ 看下面 macOS 安装
• Windows 10/11 → 看 Windows 安装
• Linux（Ubuntu） → 看 Linux 安装
• 懒得折腾 → 看 Docker 安装（任何系统都行）

---

macOS 安装

适用于 macOS 12 Monterey 及以上（M1/M2/M3 芯片也支持）

第一步：打开终端

按 Command（⌘）+ 空格，输入「终端」，按回车打开。

第二步：安装 Homebrew（没有的话）

把下面这行粘贴到终端，按回车：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

💡 Homebrew 是 macOS 上的软件包管理器，相当于苹果版的「软件商店」，免费。
安装过程需要 5-15 分钟，期间会要求输入电脑密码（输入时屏幕不显示字符，正常的）。

第三步：安装系统依赖

# 安装绘图库和视频工具
brew install cairo pango ffmpeg pkg-config

# 安装中文字体（不装的话中文会显示乱码）
brew install --cask font-noto-sans-cjk

⏱ 预计耗时：5-10 分钟（取决于网速）

第四步：安装 Python（建议用 uv 管理）

# 安装 uv（现代 Python 包管理器，速度是 pip 的 10-100 倍）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 让终端识别 uv 命令（关闭终端重新打开也行）
source ~/.zshrc

第五步：克隆并安装项目

# 下载项目代码
git clone https://github.com/bcefghj/math-animation-mcp.git
cd math-animation-mcp

# 创建虚拟环境并安装（约 5-10 分钟）
uv venv .venv
source .venv/bin/activate
uv pip install -e ".[web,ocr]"

第六步：验证安装

# 测试是否安装成功
python -c "import manim; print('Manim OK')"
python -c "from math_animation_mcp.utils.sandbox import render_manim_code; print('MCP OK')"

两行都输出 OK 就说明安装成功了！

第七步：启动！

# 启动 Web 界面
python -m math_animation_mcp --web

# 输出类似：Running on local URL: http://127.0.0.1:7860

打开浏览器访问 http://127.0.0.1:7860，就能用了！

---

Windows 安装

适用于 Windows 10（1903 及以上）/ Windows 11

第一步：安装 Python

1. 打开 https://www.python.org/downloads/
2. 点击「Download Python 3.11.x」（选 3.11 或更新版本）
3. 关键：安装时勾选「✅ Add Python to PATH」
4. 点击「Install Now」

第二步：安装 Chocolatey（Windows 的软件包管理器）

以管理员身份打开 PowerShell（开始菜单 → 搜索 PowerShell → 右键「以管理员身份运行」）：

Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

第三步：安装 Manim 和 FFmpeg

在管理员 PowerShell 中继续：

choco install manimce ffmpeg -y

⏱ 预计耗时：10-20 分钟

第四步：安装 MiKTeX（LaTeX 环境，用来渲染数学公式）

1. 打开 https://miktex.org/download
2. 下载并运行安装程序
3. 安装时选择「Install missing packages automatically: Yes」

⏱ 预计耗时：10-20 分钟

第五步：克隆并安装项目

在普通 PowerShell（不需要管理员）中：

git clone https://github.com/bcefghj/math-animation-mcp.git
cd math-animation-mcp
pip install -e ".[web]"

第六步：启动！

python -m math_animation_mcp --web

打开浏览器访问 http://localhost:7860

---

Linux 安装

适用于 Ubuntu 20.04 / 22.04 / 24.04（Debian 系列）

# 第一步：安装系统依赖
sudo apt update
sudo apt install -y \
    libcairo2-dev libpango1.0-dev \
    ffmpeg python3-pip python3-venv \
    texlive-full fonts-noto-cjk \
    pkg-config cmake git

# 第二步：克隆项目
git clone https://github.com/bcefghj/math-animation-mcp.git
cd math-animation-mcp

# 第三步：创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 第四步：安装
pip install -e ".[web,ocr]"

# 第五步：启动
python -m math_animation_mcp --web

---

Docker 安装（最懒最稳）

什么都不用装，只需要有 Docker。适合任何平台（Mac/Win/Linux）。

第一步：安装 Docker Desktop

• Mac：https://www.docker.com/products/docker-desktop/ → 下载 Mac 版 → 双击安装
• Windows：同上，下载 Windows 版
• Linux：sudo apt install docker.io docker-compose-v2

第二步：一键启动

git clone https://github.com/bcefghj/math-animation-mcp.git
cd math-animation-mcp
docker compose up -d

第一次运行会下载镜像，约需 3-8 分钟（视网速）。

第三步：打开浏览器

访问 http://localhost:7860，直接使用！

停止服务：

docker compose down

更新到最新版：

git pull
docker compose up -d --build

---

🎮 使用教程

教程 1：Web 界面生成你的第一个动画

1. 启动服务后，打开浏览器访问 http://localhost:7860
2. 在「输入描述」框中输入（中英文都行）：

   帮我做一个勾股定理的证明动画，适合初中生看，用蓝白配色
   

3. 选择「风格」：three_blue_one_brown（默认）
4. 选择「质量」：low（最快预览，约 15 秒出结果）
5. 点击「生成动画」按钮
6. 等待渲染完成，视频自动在右侧播放
7. 点击「下载」保存到本地

💡 小技巧：先用 low 质量预览，满意后再切到 medium 或 high 生成高清版

---

教程 2：在 Cursor AI 里对话式生成

需要先完成 Cursor MCP 配置

打开 Cursor，Cmd+L（Mac）/ Ctrl+L（Windows）打开对话，直接输入：

示例 1：基础动画

帮我做一个展示正弦函数 y=sin(x) 的动画，展示振幅、频率、相位变化

示例 2：高考题讲解

帮我做一个 2025 高考数学第 18 题（椭圆）的讲解动画，
要求：题目先展示 → 一步步求解方程 → 画出椭圆图形 → 动点演示性质

示例 3：上传 PDF

@数学试卷.pdf 帮我讲解第 3 题，可汗学院风格，高中生受众

示例 4：对话修改

（上一个动画太快了）帮我把动画速度调慢一半，字体再大一点

---

教程 3：直接运行案例代码

项目自带 27 个可直接运行的案例：

cd math-animation-mcp
source .venv/bin/activate

# 运行 2025 高考第 19 题（导数）讲解
python3 -c "
import sys; sys.path.insert(0, 'src')
from math_animation_mcp.utils.sandbox import render_manim_code

with open('examples/gaokao_2025/gaokao_2025_19_derivative.py') as f:
    code = f.read()

result = render_manim_code(code, quality='low', output_dir='./output')
if result.success:
    print(f'成功！视频保存在: {result.file_path}')
"

批量运行所有案例：

# 运行 15 个基础案例（约 5 分钟）
python examples/basic_math/test_all_cases.py

# 运行 12 个进阶长案例（约 10 分钟）
python examples/basic_math/test_long_cases.py

---

教程 4：通过命令行 MCP Server 使用

# 启动 MCP Server（供 AI 工具调用）
python -m math_animation_mcp

# 或者直接用 uvx（无需安装）
uvx math-animation-mcp

配合 Claude Desktop 使用，在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "math-animation": {
      "command": "uvx",
      "args": ["math-animation-mcp"]
    }
  }
}

---

🛠 常用命令速查

# 启动 Web 界面
python -m math_animation_mcp --web

# 命令行直接渲染
python -m math_animation_mcp render \
  --text "勾股定理证明" \
  --style three_blue_one_brown \
  --quality medium \
  --output ./my_videos/

# 渲染指定 .py 文件
python -m math_animation_mcp render-file ./my_scene.py

# 查看所有可用模板
python -m math_animation_mcp list-templates

# 检查环境
python -m math_animation_mcp check

---

🎨 6 种视觉风格

风格	命令	背景	适合
three_blue_one_brown	默认	深灰	科普、大学
khan_academy	--style khan_academy	白色	中小学
textbook	--style textbook	浅灰	正式教材
playful	--style playful	暖黄	小学低龄
dark_tech	--style dark_tech	纯黑	竞赛、CS
blackboard	--style blackboard	深绿	模拟课堂

对话切换：「换成黑板风格」「用可汗学院配色」

---

📐 支持的知识点范围

点击展开完整列表

高中数学

• 函数与导数：指数函数、对数函数、三角函数、导数计算、单调性分析、极值最值
• 圆锥曲线：椭圆/双曲线/抛物线的方程、焦点性质、离心率、切线
• 立体几何：棱柱/棱锥/球，线面角、二面角、空间向量法证明
• 数列：等差/等比、递推数列、数学归纳法
• 概率统计：古典概型、条件概率、贝叶斯、正态分布、频率直方图

高中物理

• 力学：牛顿定律、抛体运动、圆周运动、简谐振动、弹性势能
• 电磁学：库仑力、电场线、电势、安培力、电磁感应、法拉第定律

大学数学

• 微积分：极限定义（ε-δ）、导数、积分、泰勒展开、微分方程
• 线性代数：矩阵运算、行列式、特征值、线性变换、相空间
• 概率论：随机变量、期望、方差、中心极限定理

计算机科学

• 排序算法（冒泡/归并/快排/堆排）
• 数据结构（树、图、哈希表）
• 算法复杂度分析

---

🤖 MCP 工具列表（供 AI 助手调用）

展开 21 个工具说明

工具名	功能
render_animation	渲染完整视频（主工具）
preview_scene	快速低清预览
render_gif	导出 GIF 动图
list_templates	列出所有预置模板
get_template	获取模板源代码
search_templates	关键词搜索模板
detect_input_type	自动识别输入类型
parse_pdf	解析 PDF 提取公式
parse_image	OCR 图片识别数学公式
fix_ocr_errors	修复 OCR 常见错误
normalize_content	结构化内容
analyze_error	分析渲染错误
fix_latex_error	自动修复 LaTeX 错误
fix_python_error	自动修复 Python 错误
set_style	切换视觉风格
set_preferences	更新用户偏好
get_preferences	读取当前设置
set_branding	设置水印和品牌
export_video	格式转换/比例调整
add_subtitles	烧录字幕
add_tts_narration	AI 配音（即将推出）

---

❓ 常见问题 FAQ

Q：完全不会编程，能用吗？
完全可以！Docker + Web 界面，打开浏览器说话就行，不需要写任何代码。

Q：渲染需要多长时间？

质量	30 秒动画耗时	建议用途
low (480p)	10-30 秒	快速预览
medium (720p)	30-90 秒	日常使用
high (1080p)	2-5 分钟	最终输出

Q：中文显示方框或乱码怎么办？

# macOS
brew install --cask font-noto-sans-cjk

# Ubuntu
sudo apt install fonts-noto-cjk

# Windows：下载 Noto CJK 字体
# https://www.google.com/get/noto/

Docker 版已预装所有字体，不会有这个问题。

Q：渲染失败了怎么办？
系统内置自动修复：失败后自动重试最多 5 次，包括 LaTeX 修复、Python 语法修复。如果仍失败，会降级到预置模板保证出图。

Q：可以做竖屏短视频版本吗？

export_video("output.mp4", aspect_ratio="9:16")  # 适合抖音/视频号

或对话说：「导出竖屏版，9:16 比例」

Q：可以加自己的水印吗？

set_branding(watermark="张老师课堂", intro_text="张老师数学")

或对话说：「加个水印，写上"张老师课堂"」

Q：如何更新到最新版本？

cd math-animation-mcp
git pull
source .venv/bin/activate
uv pip install -e . --upgrade

---

📁 项目结构

math-animation-mcp/
├── 📁 src/math_animation_mcp/
│   ├── server.py              # MCP Server（21个工具）
│   ├── web_server.py          # Gradio Web 界面
│   ├── cli.py                 # 命令行入口
│   ├── 📁 tools/              # 工具实现
│   │   ├── render_tools.py    # 渲染
│   │   ├── input_tools.py     # PDF/图片/OCR 处理
│   │   ├── repair_tools.py    # 自动修复
│   │   ├── template_tools.py  # 模板管理
│   │   ├── personalization_tools.py
│   │   └── export_tools.py
│   ├── 📁 templates/          # 预置模板库
│   │   ├── geometry/          # 几何
│   │   ├── algebra/           # 代数
│   │   ├── calculus/          # 微积分
│   │   ├── trigonometry/      # 三角
│   │   ├── statistics/        # 统计概率
│   │   ├── physics/           # 物理
│   │   └── cs/                # 计算机
│   ├── 📁 styles/presets.py   # 6种视觉风格
│   ├── 📁 config/             # 用户偏好
│   └── 📁 utils/              # 沙箱、中文支持、FFmpeg
│
├── 📁 examples/               # ✨ 可运行案例
│   ├── 📁 gaokao_2025/        # 2025 高考真题（3道大题）
│   │   ├── gaokao_2025_17_solid.py      # 立体几何
│   │   ├── gaokao_2025_18_ellipse.py    # 圆锥曲线
│   │   └── gaokao_2025_19_derivative.py # 导数压轴
│   └── 📁 basic_math/         # 基础数学（27个案例）
│       ├── test_all_cases.py            # 15个短案例
│       └── test_long_cases.py           # 12个长案例
│
├── 📁 docs/                   # 详细文档
│   ├── getting-started/
│   ├── tutorials/
│   └── faq/
│
├── 🐳 Dockerfile
├── 🐳 docker-compose.yml
├── 🔧 install.sh              # macOS/Linux 一键安装
├── 🔧 install.ps1             # Windows 一键安装
└── 📄 pyproject.toml

---

🙏 致谢

• Manim Community — 动画引擎
• 3Blue1Brown — 灵感来源
• Model Context Protocol — AI 工具集成标准
• Gradio — Web 界面框架

---

📄 开源协议

MIT License — 免费用于个人和商业用途，保留版权声明即可。

---

Made with ❤️ for math education | 让每一道数学题都能被看见