Manim MCP

Manim MCP

一个基于 Docker 的环境，用于使用 Manim 创建数学动画，提供 CLI 界面和 Web API，并支持 Model Context Protocol（MCP），以便与 AI 助手集成。

📑 概览

此项目提供：

1. 容器化 Manim 环境：在隔离、可复现的 Docker 环境中运行 Manim
2. Web API：通过 HTTP 请求创建和管理 Manim 动画
3. MCP 集成：直接与 Claude 等 AI 助手交互
4. 文件管理：上传脚本并下载生成的动画

🚀 快速开始

先决条件

• 系统中已安装 Docker 和 Docker Compose

安装

选项 1：使用预构建镜像（推荐）

直接从 Docker Hub 拉取预构建镜像：

docker pull wstcpyt/manim-docker-mcp:latest

然后使用 docker-compose 运行：

docker compose up -d

选项 2：本地构建

1. 克隆仓库：

   git clone https://github.com/YOUR_USERNAME/manim-docker-mcp.git
   cd manim-docker-mcp
   

2. 构建 Docker 镜像：

   docker compose build
   

使用方法

CLI 模式

在 animations 目录中创建一个 Python 文件（参见下方示例），然后运行：

docker compose run manim -pql animations/example.py ExampleScene

API 模式

启动 API 服务：

docker compose up -d manim-api

在 http://localhost:8000/docs 查看 API 文档

🎬 创建动画

基本示例

创建文件 animations/example.py：

from manim import *

class CircleToSquare(Scene):
    def construct(self):
        circle = Circle()
        circle.set_fill(BLUE, opacity=0.5)

        square = Square()
        square.set_fill(RED, opacity=0.5)

        self.play(Create(circle))
        self.wait()
        self.play(Transform(circle, square))
        self.wait()

运行动画

# CLI mode with preview (-p), low quality (-ql)
docker compose run manim -pql animations/example.py CircleToSquare

# API mode
curl -X POST "http://localhost:8000/run-manim?filepath=/manim/temp/circle_example.py&scene_name=CircleToSquare&quality=low_quality"

📂 项目结构

manim-docker-mcp/
├── animations/           # Manim animation scripts
├── app/                  # FastAPI application
├── media/                # Generated animations (CLI mode)
├── output/               # Generated animations (API mode)
├── temp/                 # Temporary files
├── uploads/              # Uploaded animation scripts
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker Compose configuration
└── README.md             # This file

🔧 配置

质量设置

标志	分辨率	帧率	适用场景
-ql	480p	15fps	快速预览
-qm	720p	30fps	通用场景
-qh	1080p	60fps	演示
-qk	1440p	60fps	成品视频

其他实用标志

• -p：预览输出文件
• -t：透明背景
• --save_last_frame：仅渲染最后一帧
• -c COLOR：设置背景颜色

🌐 API 文档

核心端点

列出文件

GET /list-files?directory=/manim

写入文件

POST /write-file?filepath=/manim/temp/example.py

运行动画

POST /run-manim?filepath=/manim/temp/example.py&scene_name=CircleToSquare

下载动画

GET /download-file?filepath=/media/videos/example/480p15/CircleToSquare.mp4

完整 API 文档可通过 /docs 端点查看。

🤖 AI 助手集成（MCP）

此项目支持 Model Context Protocol（MCP），使 AI 助手能够：

1. 根据自然语言描述创建 Manim 脚本
2. 运行动画并提供下载链接
3. 浏览和管理生成的媒体文件

MCP 会话示例：

User: Create an animation showing a circle morphing into a square
AI: I'll create that for you...

🔍 高级用法

自定义 LaTeX

容器中包含精简版 LaTeX 安装。可以在动画中使用自定义 LaTeX：

formula = MathTex(r"\int_{a}^{b} f(x) \, dx = F(b) - F(a)")
self.play(Write(formula))

挂载自定义目录

修改 docker-compose.yml 文件以挂载其他目录：

volumes:
  - ./my_custom_dir:/manim/custom

🛠️ 故障排除

常见问题

• Docker 未运行：请确保 Docker 守护进程正在运行
• 权限错误：容器需要对挂载的卷具有写入权限
• 缺少媒体文件：请检查正确的输出目录（CLI 使用 media/，API 使用 output/）

获取帮助

如果遇到问题：

1. 查看 Manim 文档
2. 搜索现有 GitHub 问题
3. 创建新问题，并详细描述遇到的问题

📜 许可证

此项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Manim Community 提供出色的动画引擎
• 感谢 FastAPI 提供 Web 框架
• 感谢 Model Context Protocol 提供 AI 集成