OpenToonz MCP

---

我为什么开发它

如今，大多数“AI 动画”都会生成无法编辑的成片。动画师需要的恰恰相反：可以修正的绘图、可以重新调整的时间安排，以及可以交给制作流程中下一位成员的场景。

OpenToonz 是 Toonz 的开源版本；Studio Ghibli 曾对 Toonz 进行定制，并将其用于电影制作。它本身已具备 2D 制作流程所需的一切：矢量层、摄影表格、移动台、摄像机和合成器。它缺少的只是让助手能够使用它的方式。

OpenToonz MCP 就是这座桥梁。你描述一个镜头，助手就会安排布局、绘制关键姿势、补间、按一拍一帧、两拍一帧或三拍一帧的节奏安排动画、添加镜头运动并渲染。最终得到的是一个标准的 OpenToonz 场景。你可以打开它，随意修改、保存，然后让助手接着完成。你的修改都会保留。

— konkomaji · konkomaji.com

适用人群

• 动画师和导演：希望快速制作布局、动态分镜、补间和镜头运动，然后再亲手完成作品。
• 独立工作室和个人创作者：没有完整团队，也能制作短片、解说视频、音乐视频或游戏过场动画。
• 动画教师和学生：这些工具遵循经典动画原理（渐入／渐出、运动弧线、预备动作、跟随动作），因此生成的内容是可以逐帧检查的完整示例。
• 开发者：构建创意 AI 工具时，需要的是真实、可检查的 2D 制作流程，而不是像素图像。

功能

🎨 原生矢量绘图	形状、SVG 路径和压感笔刷笔触会转换为 OpenToonz .pli 矢量层级。转换由 OpenToonz 自行完成，因此绘图可使用 OpenToonz 的矢量工具完全编辑。
✍️ 手绘质感	笔压渐细。微妙的线条抖动，在保持帧中保持静止。可选的线条沸腾效果。动漫赛璐璐阴影或钢笔排线（灵感来自 p5.brush），以及彩色描线。风格预设：anime、feature、cartoon、sketch、clean。
🎞️ 动画师的时序控制	带慢入慢出的中间帧、弧线，以及保持面积不变的挤压与拉伸。Xsheet 曝光可设为一拍一张、两拍一张或三拍一张。根据文本制作眨眼和口型同步。
🦘 内置动画原理	animate_action 根据经典比例添加预备动作、过冲和稳定动作。物理工具可制作精确符合重力的弹跳（带材质预设）、配方跳跃，以及基于弹簧的头发、尾巴和布料跟随动作。
🧍 真实人体的行走与奔跑	build_character 根据已公开的身体测量数据，为任意年龄和性别（幼儿、女孩、男孩、青少年、女性、男性、老妇人、老年男性）制作侧视剪纸骨架；还可选用全国健康调查中的地区平均数据（例如美国、印度、西孟加拉邦、日本、英国或尼日利亚的数据）。walk_cycle 和 run_cycle 根据步态研究为角色制作动画：脚掌着地并从脚跟滚动到脚尖、双骨骼腿部 IK、倒立摆行走，以及腾空阶段精确符合重力的弹簧质点奔跑。每次调用都会报告步频、步长、膝盖角度和脚部滑动情况，方便检查动作。
🎬 制片厂风格	apply_look 会添加吉卜力、klaus、spider_verse、漫画、anime_satsuei、绘画风或 cartoon_saloon 风格，并将其作为真正的 OpenToonz fx 节点（泛光、形体阴影和轮廓光、错位色版、颗粒）。它们在 FX Schematic 中仍可编辑，remove_look 则可将其干净移除。
🎥 镜头运用	使用视差图层的摇镜、指数推拉、冲击和创伤抖动，以及平滑的镜头跟随。在镜头移动可能露出空白背景或摇摄速度快到足以产生频闪效果之前发出警告。
🖼️ 导入自己的美术素材	将 SVG 文件导入为可编辑形状。放置图像，或让 OpenToonz 自带的矢量化工具描摹图像并转换为矢量层级。构建可重复使用的部件库（包含口型图等变体的模型表）。
🔁 兼容手动编辑	场景文件是唯一可信来源。在 OpenToonz 中调整时序或重画并保存后，助手会读取你的更改，而不是将其覆盖。
🛡️ 安全至上	每次编辑前都会创建快照。调用失败时会自动回滚。undo 可精确还原场景和绘图，写入前会验证内容，并通过逐场景锁防止并发写入。
🧠 持续记忆和改进	每个场景都会保存笔记和日志。错误、渲染评审和你的反馈会转化为分级经验，供后续会话参考；tune_style 则会将偏好的默认设置永久保存。

由 OpenToonz 渲染的赛璐璐阴影、抖动和压感渐细效果	SVG 路径和逐点带压感的笔刷笔触

要求

• Windows 上的 OpenToonz 1.8。服务会根据 OpenToonz 的注册表项自动检测安装位置和「stuff」文件夹。
• Python 3.10+。
• PATH 中的 ffmpeg，用于输出 MP4 和 GIF（输出 PNG 序列无需此工具）。

安装

pip install opentoonz-mcp
# or run without installing:
uvx opentoonz-mcp

请使用 pip 26.2.2+ 或 uv 0.13.4+。 较旧版本仍信任在 2026 年 10 月 eMudhra 事件后被撤销的 emSign 证书颁发机构。请先使用 python -m pip install --upgrade pip certifi 或 UV_SYSTEM_CERTS=true uv self update 升级。软件包本身要求 certifi>=2026.10.19。

Claude Code

claude mcp add opentoonz -- uvx opentoonz-mcp

Claude Desktop、Cursor 和其他 MCP 客户端

{
  "mcpServers": {
    "opentoonz": {
      "command": "uvx",
      "args": ["opentoonz-mcp"],
      "env": {
        "OPENTOONZ_HOME": "C:\\Program Files\\OpenToonz",
        "OPENTOONZ_STUFF": "C:\\OpenToonz stuff"
      }
    }
  }
}

env 块是可选的。仅当自动检测选错安装位置时才使用。

变量	含义	默认值
OPENTOONZ_HOME	包含 OpenToonz.exe 和 tcomposer.exe 的文件夹	从 Windows 卸载项检测，然后为 C:\Program Files\OpenToonz
OPENTOONZ_STUFF	OpenToonz“stuff”文件夹（TOONZROOT）	从 HKLM\SOFTWARE\OpenToonz\OpenToonz 检测
OTMCP_WORK	保存状态、撤销快照、渲染和教程的位置	%LOCALAPPDATA%\opentoonz-mcp

请让助手先运行 opentoonz_info。它会报告检测到的内容以及缺少的内容。

试试看

创建一个 4 秒的动漫风格场景：一个圆滚滚的麻糬角色站在山坡上。它眨眼、蹲下、跳起并落地，带有挤压和拉伸效果，同时镜头向右平移并呈现视差。然后渲染为 MP4。

在描线图层上导入我的草图 C:\art\pose.png，使用中线描摹，然后将其补间到下一个偶数帧上的关键帧。

制作一位老妇人和一个七岁女孩，让她们一起走过画面。

在 OpenToonz 中打开场景。我会修复第 12 帧的手臂。……完成了：从第 13 帧继续。

一次良好的会话应该像一条工作室流水线：

1. scene_context（始终首先执行）
2. create_scene
3. add_note（故事）
4. 布局：图层、定位杆和摄像机
5. 关键绘图，然后使用 inbetween 和时间设置
6. set_pivot，然后设置关键帧、使用 animate_action 和物理效果（或针对人物使用 build_character 和 walk_cycle）
7. camera_move，然后使用 apply_look 打造工作室级效果
8. validate_scene、contact_sheet、render

包含全部参数的 52 个工具完整列表见 docs/TOOLS.md。

工作原理

assistant ──MCP──► opentoonz-mcp ──► .tnz scene (edited in place, lossless)
                         │
                         ├─► SVG drawings ──► OpenToonz.exe (headless script) ──► native .pli ──► pen pressure
                         ├─► images ───────► OpenToonz vectorizer ───────────────► traced .pli
                         └─► tcomposer.exe (OpenToonz's renderer) ──► PNG ──► ffmpeg ──► MP4 / GIF

所有涉及 OpenToonz 数据的内容都会通过 OpenToonz 本身进行验证。例如，关键帧插值是对 OpenToonz 求值器的移植，测试会逐帧将其与真实的 tcomposer 渲染结果进行比较（误差在 1.5 px 以内）。

详情请参阅 docs/WHITEPAPER.md、docs/ARCHITECTURE.md 和 docs/FORMAT_NOTES.md。

限制

• 首先支持 Windows。 本项目基于 Windows 和 OpenToonz 1.8 开发并测试。设置 OPENTOONZ_HOME 后，其他平台或许也能运行，但未经测试。
• 绘图由形状、路径、笔刷笔触和导入的美术素材构成。 没有内置图像生成器。请自备美术素材，或让助手通过路径和部件进行创作。
• 重新绘制会替换该图层上的编辑内容。 如果你在 GUI 中重新绘制助手绘制过的图层，除非明确要求（force=true），否则助手不会覆盖它。
• 渲染测试需要本地安装 OpenToonz。 CI 仅运行单元测试。

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。更改记录在 CHANGELOG.md 中。

致谢

• 由 konkomaji 构建。
• 由 OpenToonz（BSD-3-Clause）提供支持，OpenToonz 不随本项目打包。感谢 DWANGO、Digital Video 的 Toonz 原团队、吉卜力工作室以及所有 OpenToonz 贡献者。请参阅 NOTICE。
• 本项目与 OpenToonz、DWANGO、Digital Video 或吉卜力工作室均无关联。

本项目根据 MIT License 发布。