sanhang-mcp

三行弦图（MathMagic）的 MCP 服务。把一句自然语言的数学描述，渲染成一段 Manim 动画视频，返回可直接播放的 mp4 链接和可复用的 Manim 代码。

和其他 manim 系 MCP 最大的区别：本机不需要安装 Manim、LaTeX、ffmpeg，也不需要显卡。渲染在托管后端完成，本地只跑一个纯标准库的 Python 进程。

• 输入：一句话，例如「画出 y=sin(x) 在 0 到 2π 上的图像，用一个红点演示它随 x 增大而运动」

• 输出：mp4 直链 + 封面图 + 完整 Manim 代码 + 渲染耗时

• 依赖：Python 3.8 及以上，能访问 sanhangmath.top，仅此两项

为什么单独做一个

社区里已有的 manim MCP 大多走「本地装 Manim 然后执行代码」的路线：本地先装一整套 Python、Manim、LaTeX、ffmpeg（几个 GB），再把模型写的代码丢进去跑。这对笔记本不友好，对沙箱环境更难落地。

服务端自带提示词工程、版本对齐、渲染重试、多清晰度转码与语义缓存，客户端都不需要操心。

Related MCP server: Manim MCP Server

快速开始

前置条件

只有两件事：

1. 安装 uv（一个命令，之后 uvx 会自动下载并托管 Python，本机不需要预装 Python）：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或者 macOS 用 Homebrew
brew install uv

2. 能访问 sanhangmath.top。

三种安装方式

默认推荐 PyPI，一条命令，不需要下载任何文件：

uvx sanhang-mcp --version

PyPI 走不通时（例如公司网络限制），可以直接从 GitHub 仓库装，效果一样：

# 指定版本标签，可复现
uvx --from "git+https://github.com/sanhangkc/sanhang-mcp@v1.0.0" sanhang-mcp --version
# 跟随 main 分支
uvx --from git+https://github.com/sanhangkc/sanhang-mcp sanhang-mcp --version

内网或 GitHub 也受限时，把源码包下载下来直接跑，零第三方依赖：

python3 sanhang_mcp.py --version

三种方式装出来的都是同一个版本，配置文件里的差异只在 command 与 args：用 PyPI 就写 uvx sanhang-mcp，用 GitHub 就把 git+https 地址写进 args。

先自检，再接入

终端里跑一次，确认后端通、环境也对：

uvx sanhang-mcp --check
uvx sanhang-mcp --whoami

前者看到 OK https://sanhangmath.top/api -> {"status": "healthy", ...} 就说明通；后者打印你的配额标识（首次运行自动生成，存在 ~/.sanhang-mcp/identifier，不需要手动配置）。

注意这里的终端命令只是自检用。真正使用是把下一节的配置写进客户端，让客户端去拉起这个进程；不需要在终端里常驻运行。

也可以直接拿源码跑，零第三方依赖：

python3 sanhang_mcp.py --check
python3 sanhang_mcp.py --version

接入客户端

这个服务在各客户端里统一叫 sanhang-mcp。三种常见配置如下。

WorkBuddy，配置文件 ~/.workbuddy/mcp.json：

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

Claude Desktop，配置文件 claude_desktop_config.json（macOS 在 ~/Library/Application Support/Claude/）：

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

Cursor，配置文件 ~/.cursor/mcp.json，格式同上。DeepSeek harness、Cline、Continue 等只要支持 stdio MCP，写法一致。

没装 uv 的话，把 command 换成 python3，args 换成 sanhang_mcp.py 的绝对路径。Windows 上必须写 python.exe 的绝对路径，相对路径会启动失败。

macOS 上有个必踩的坑要提前说：从 Finder 或程序坞启动的图形客户端（Claude Desktop、WorkBuddy、Cursor）拿到的 PATH 只有 /usr/bin:/bin:/usr/sbin:/sbin，不含 ~/.local/bin 和 /opt/homebrew/bin。所以 command 写 uvx 会启动失败，必须写绝对路径，用 which uvx 查一下你的实际位置：

| 安装方式 | command 应该写 | | Homebrew | /opt/homebrew/bin/uvx | | 官方脚本 curl 安装 | /Users/<你的用户名>/.local/bin/uvx |

Windows 同理，写 uvx.exe 的完整路径。

想固定配额标识（例如一台机器多人共用、或想让用量归到自己名下），加一段 env：

"env": { "SANHANG_USER_IDENTIFIER": "your-name" }

改完配置要彻底重启客户端才会加载。WorkBuddy 还需要在连接器页右上角的「自定义连接器」里点一次信任。

三个工具

典型用法有两种。

第一种，直接阻塞等结果，适合大多数客户端：

sanhang_render({ "prompt": "画出 y=x^2 的图像，在顶点标一个红点" })

第二种，先提交再轮询，适合有工具调用超时限制的客户端：

sanhang_render({ "prompt": "...", "wait": false })          -> 拿到 task_id
sanhang_task({ "task_id": "...", "action": "wait", "max_wait_seconds": 300 })

渲染通常 30 到 90 秒。命中缓存时秒回，同一描述第二次调用基本是 0.1 秒。

环境变量

旧版 MANIM_MCP_ 前缀仍然可用，两个前缀同时出现时 SANHANG_ 优先。

自测

仓库自带一个最小 MCP 客户端，不需要任何外部依赖，用来验证握手、工具发现、错误码和输出纯净性：

python3 test_client.py                         # 20 项协议断言，约 2 秒
python3 test_client.py --generate "画个抛物线"   # 真实渲染一次
python3 test_client.py --gallery               # 只读工具，不花钱

工作方式

MCP 客户端 --stdio JSON-RPC--> sanhang-mcp 进程 --HTTPS--> sanhangmath.top/api
                                                           |- LLM 出码
                                                        |- Manim + LaTeX 渲染
                                                           |- ffmpeg 转码

协议版本 2025-06-18，兼容 2025-03-26 与 2024-11-05。stdio 传输，一行一条 JSON-RPC，stdout 只写协议消息，日志全部走 stderr。每个请求各开线程处理，长渲染期间 ping 仍然能回；带 progressToken 时会回传 notifications/progress；收到 notifications/cancelled 会中断轮询并请求后端停止渲染。

边界

• 渲染能力受后端限制，复杂三维场景、超长动画可能超时，建议把描述拆小。

• 后端有配额：同一标识每天 50 次、终身 1000 次，另有每分钟 5 次的突发限制。超限返回 429，不是服务故障。

• 高清档位、视频下载、代码免水印复制属于站点会员能力，免费调用返回 480p15 在线观看版本。

• 视频链接是公网直链，任何拿到链接的人都能播放。

目录结构

.
├── sanhang_mcp.py     # 服务端，零第三方依赖
├── test_client.py     # 最小 MCP 客户端与协议自测
├── pyproject.toml     # 打包元数据，py-modules 入口
├── README.md
└── LICENSE

License

MIT