OpenToonz MCP

Let an AI assistant animate inside OpenToonz, the open-source 2D studio tool, and keep every frame editable.

_{Made entirely with this server's tools. The character, background and timing are real OpenToonz vector levels, xsheet cells and keyframes, so you can open the scene and keep animating by hand.}

Why I built this

Most "AI animation" today produces a finished video you can't edit. Animators need the opposite: drawings they can fix, timing they can retime, and a scene they can hand to the next person in the pipeline.

OpenToonz is the open-source release of Toonz, the software Studio Ghibli customised and used on its films. It already has everything a 2D pipeline needs: vector levels, an xsheet, pegbars, cameras and a compositor. What it lacked was a way for an assistant to use it.

OpenToonz MCP is that bridge. You describe a shot. The assistant lays it out, draws key poses, in-betweens them, times them on ones, twos or threes, adds camera work, and renders. The result is a normal OpenToonz scene. You can open it, change anything, save it, and ask the assistant to continue. Your edits are kept.

— konkomaji · konkomaji.com

Who it's for

• Animators and directors who want fast layouts, animatics, in-betweens and camera passes they can then finish by hand.
• Indie studios and solo creators making shorts, explainers, music videos or game cutscenes without a full crew.
• Teachers and students of animation. The tools follow the classic principles (slow in/out, arcs, anticipation, follow-through), so the output is a worked example you can inspect frame by frame.
• Developers building creative AI tools who need a real, inspectable 2D pipeline rather than pixels.

What it can do

Cel shadow, wobble and pressure taper, rendered by OpenToonz	SVG paths and brush strokes with per-point pressure

Requirements

• OpenToonz 1.8 on Windows. The server auto-detects the install and the "stuff" folder from OpenToonz's registry entries.
• Python 3.10+.
• ffmpeg on PATH for MP4 and GIF output (PNG sequences work without it).

Install

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

Claude Code

claude mcp add opentoonz -- uvx opentoonz-mcp

Claude Desktop, Cursor and other MCP clients

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

The env block is optional. Use it only if auto-detection picks the wrong install.

Ask the assistant to run opentoonz_info first. It reports what it found and anything missing.

Try it

Create a 4-second anime-style scene of a round mochi character on a hill. It blinks, crouches, jumps and lands with squash and stretch while the camera pans right with parallax. Then render an MP4.

Import my sketch C:\art\pose.png on a traced layer with centerline tracing, then in-between it to the next key on twos.

Build an old woman and a seven-year-old girl, and have them walk across the frame together.

Open the scene in OpenToonz. I'll fix the arm on frame 12. … Done: carry on from frame 13.

A good session looks like a studio pipeline:

1. scene_context (always first)
2. create_scene
3. add_note (story)
4. Layout: layers, pegs and camera
5. Key drawings, then inbetween and timing
6. set_pivot, then keys, animate_action and physics (or build_character and walk_cycle for people)
7. camera_move, then apply_look for a studio finish
8. validate_scene, contact_sheet, render

The full list of 52 tools with every parameter is in docs/TOOLS.md.

How it works

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

Everything that touches OpenToonz data is checked against OpenToonz itself. The keyframe interpolation, for example, is a port of OpenToonz's evaluator, and tests compare it frame by frame with real tcomposer renders (within 1.5 px).

The details are in docs/WHITEPAPER.md, docs/ARCHITECTURE.md and docs/FORMAT_NOTES.md.

Limitations

• Windows first. It is developed and tested on Windows with OpenToonz 1.8. Other platforms may work with OPENTOONZ_HOME set, but they are untested.
• Drawing comes from shapes, paths, brush strokes and imported art. There is no built-in image generator. Bring your own art, or have the assistant compose it from paths and parts.
• Redrawing replaces your edits on that layer. If you redraw, in the GUI, a layer the assistant drew, the assistant won't overwrite it unless told to (force=true).
• Render tests need a local OpenToonz. CI runs the unit tests only.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Changes are recorded in CHANGELOG.md.

Credits

• Built by konkomaji.
• Powered by OpenToonz (BSD-3-Clause), which is not bundled. Thank you to DWANGO, the original Toonz team at Digital Video, Studio Ghibli, and every OpenToonz contributor. See NOTICE.
• This project is not affiliated with OpenToonz, DWANGO, Digital Video or Studio Ghibli.

Released under the MIT License.