OpenToonz MCP

Install paths, version, scenes, and whether the OpenToonz GUI is running.

Takes no parameters.

CALL FIRST. Full current state of a scene from disk: settings, layers, timing, keyframes, outside (GUI) changes detected, notes/memory, recent journal, warnings.

Save a memory note for this scene (story, character design, decisions, todo). Shown in scene_context.

Operation history of a scene (every MCP action, outside edits detected, errors).

Studio animation rules (Ghibli/Disney/anime practice) with numbers: timing, spacing, squash, line weight, shading, camera. topic: 'rules' (numbered defaults) | 'full' | 'styles'.

Restore the scene (and any overwritten vector levels) to the state before the last N MCP writes.

Create a scene in the OpenToonz sandbox project. style: anime | feature | cartoon | sketch | clean (line weight, wobble, taper, default timing).

Bring an existing OpenToonz .tnz (made in the GUI) under MCP control. Copies it into the sandbox scenes folder if it is elsewhere. Its columns appear as 'foreign_columns' you can key/retime. A scene the MCP already manages is refused unless overwrite=true (its MCP layer data is reset).

Change scene length (frames), fps, background colour, or default drawing style.

Add a column with its own drawing level. Later layers are drawn ON TOP. mode: 'vector' (native OpenToonz vector .pli, editable in GUI, pressure lines) | 'raster' (PNG). style: override scene style for this layer (e.g. 'clean' for BG, 'sketch' for effects). parent: 'Table', a peg or another layer. boil: hand-drawn line boil on held drawings.

Add a pegbar (invisible transform node). Parent layers to it to move groups (character rigs, BG sets).

Re-parent a layer or peg to 'Table', a peg, or another layer.

Layer properties: visible, opacity (0-1, renders), boil, style (needs redraw), timing 'auto'|'manual'.

Delete a layer (column, level, drawings). Undo-able.

Draw drawing #frame on a layer (held until the next drawing when timing is auto). Shapes (canvas px, origin top-left), painted in order: circle{x,y,r} ellipse{x,y,rx,ry,rotation} rect{x,y,w,h,radius,rotation} (x,y=top-left) polygon{points,smooth} path{points,smooth=true,closed} text{x,y,text,size,anchor='mm'} svgpath{d:'M.. C.. A.. Z', transform?} - any SVG path data (detailed art: hair, hands, folds) brush{points:[[x,y,pressure 0-1],...], width:px max, color} - inked stroke with per-point pressure Paint/ink: fill, stroke, stroke_width (px; default from style), opacity, interior=true (thinner interior line), trace_line=true (iro-tore coloured line), shadow=true|{light:deg,depth:px,color} (anime cel shadow; light 90=top, 135=top-left), or shadow={style:'hatch', spacing:px, angle:deg, cross:true, gradient:0-1, jitter:0-1, width:px} for pen hatching of the shadow side (real ink strokes), human=false (perfect geometry), wobble (px). Colours: '#rrggbb', css names or [r,g,b,a].

Batch draw: drawings=[{"frame": n, "shapes": [...]}, ...]. Use for frame-by-frame animation.

Generate in-betweens (douga) between two key drawings (genga). start/end_shapes default to the drawings already on start_frame/end_frame. easing: slow_in_out (studio chart) | snappy | linear | in | out | bounce | elastic | back. step: 1 ones, 2 twos, 3 threes (default: style timing, anime=3, feature=2). arc: bow of the travel path (0.15 = natural arc). squash: 0-1 stretch round shapes along motion. Studio rule: only auto-inbetween 'tight' moves (rotation<=30deg, scale change<=25%); add a breakdown key otherwise.

Xsheet timing for a layer (sets timing=manual). cells[i] = drawing at frame i+1 (0 = blank), or run-length text '1x6 2x6 3x4 0x2' (drawing x frames). Cycle example on twos: '1x2 2x2 3x2 4x2 1x2 ...'.

Keyframe a layer, peg, or 'camera' (real OpenToonz keys, editable in GUI Function Editor). x/y: px offset from rest (+y down). rotation: deg CCW. scale*: 1.0=100%. z: depth. interp (segment starting at this key): ease | linear | constant | speed | exp. Camera: scale<1 zooms IN; use exp interp for trucks (natural zoom).

Set the rotation/scale pivot of a layer or peg without moving it (OpenToonz 'center'). x,y: canvas px. x='auto': from the layer's drawing bounds; anchor 'bottom' (feet - use for squash on the ground) | 'center' | 'top'. Do this BEFORE squash/stretch or rotation keys.

Remove keys from a target (optionally one param: x,y,rotation,scale,scale_x,scale_y,z; optional frame range).

Move a layer/peg/camera with animation principles baked in (Illusion of Life numbers): anticipation (opposite move, 15% amplitude, 25% of duration, min 3f), main move with slow-in/out, overshoot (10% past target) and damped settle (x0.45 swing) over settle_frames AFTER 'end'. to/from_: {x,y,rotation,scale,scale_x,scale_y} (px/deg/factor). from_ defaults to current value at start.

Camera work (satsuei): kind='pan': move view by dx,dy px from start..end (eased 8f). parallax={layer: ratio} makes layers move at ratio of camera speed (sky 0.05, far BG 0.3, mid 0.6, char 1.0, FG 1.8). kind='truck': zoom to 'zoom' scale (0.75 = push in 25%) with exponential interpolation. kind='shake': impact shake starting at 'start', strength px (8 default), decays x0.7/frame on ones.

Bring a picture (sketch, scanned drawing, painting, photo, AI image) into a layer. Raster layer (mode 'raster'): the image is placed as-is. Traced layer (add_layer mode='traced'): OpenToonz's own vectorizer turns it into editable vector strokes and fills on compile. trace: set the traced layer's method once: 'outline' (colour regions) | 'centerline' (ink lines). box [x,y,w,h] px (default whole canvas); fit contain | cover | stretch | none.

Import an SVG file (Inkscape/Illustrator/free assets) as editable vector shapes on a drawing. Every path becomes an 'svgpath' shape you can tween, recolour or humanize (human=true adds the hand-drawn wobble/pressure of the layer style). box [x,y,w,h] fits the art (default whole canvas).

Save a reusable part to the global model-sheet library (head, eye, hand, mouth chart, prop). shapes use the part's own coordinates; anchor [x,y] is its attachment/pivot point. variants: alternative drawings by name, e.g. {"closed": [...], "A": [...], "O": [...]}. Use in any drawing as {"type":"part","name":..,"variant":..,"x","y","scale","rotation","flip"}.

Parts in the model-sheet library with their variants.

Takes no parameters.

Physically exact bouncing (gravity parabolas, coefficient of restitution) on a layer/peg. The drawing must rest on the ground line; y offsets go UP from there. height px. fall_frames: frames for the first drop (default: real gravity for a 1.7 m character = 1080 px tall, i.e. 14.1*sqrt(height/1080)). material: rubber_ball | table_tennis | basketball | tennis | soft_rubber | bowling | balloon (sets restitution and squash). travel_x: px moved over the whole bounce, slowing with each contact. squash: area-preserving contact squash (set_pivot at the feet first).

Recipe jump on a layer/peg: anticipation crouch -> takeoff stretch -> exact parabola -> landing squash -> recovery. style: realistic | feature | cartoon (crouch depth, stretch and squash amounts). air_frames default: real gravity for the scene height (1.7 m character = frame height).

Overlapping action / follow-through from a damped spring (second-order system). The target reacts to the driver's motion (driver's `param`, exact OpenToonz values). mode 'follow': target_param = spring(driver) (a separate object trailing the driver). mode 'offset': target_param = gain * (spring(driver) - driver) (a part PARENTED to the driver: hair, ears, tail, cloth; use target_param='rotation' with gain in deg per px for a swing). frequency Hz (hair 2-2.5, ears 3, belly 4-5, cape 1.2), damping 0.25-0.5 (overshoot 15-45%), response < 0 anticipates. Keep frequency <= 4 Hz on ones, <= 2.5 Hz on twos (aliasing).

Follow a layer/peg with the camera using critically damped smoothing (game-camera SmoothDamp). smooth_time in frames (7 = 0.3 s); axis x | y | xy; offset px added to the followed position.

Insert a blink into a layer's xsheet at `start` (switches the layer to manual timing). pattern: standard (H C C H) | quick | anime_twos | physiological | sleepy | double. Drawings: the eye open/half/closed drawing numbers on that layer.

Animate a mouth from text (no audio): each mouth shape is a VARIANT of a library part (anime3: closed/half/open; blair: AI E O U WQ MBP FV L etc rest). Draws one drawing per shape on the layer and writes the xsheet from `start` (2-frame minimum holds). Shift `start` 2 frames earlier than the audio (mouths lead sound).

Body proportions for drawing a person, from anthropometric data (Drillis-Contini segment lengths, de Leva masses, CDC/NHANES stature, growth-standard head ratios). person: baby | toddler | boy | girl | child | teen | teen_boy | teen_girl | young_man | young_woman | man | woman | old_man | old_woman (or give age years / label and sex). Returns heights from the floor, segment lengths, front widths, side depths (px), heads tall, mass fractions, centre of mass, notes. Scale: height_px, or px_per_m (340 = 1.75 m adult about 600 px; keep one px_per_m per scene). region (list_regions): population averages from national health surveys (stature, leg length via sitting-height ratio); bmi: a number, or 'average' for the region's surveyed mean (default: a neutral build). Averages only: individuals vary far more than regions do.

Regions with surveyed body averages for anatomy_reference / build_character (region=...).

Takes no parameters.

Build a side-view cut-out character rig with real proportions for the age and sex. Creates a root peg '<name>' at the hips and 16 vector layers '<name>_<part>' (torso, head, upper arm, forearm, hand, thigh, shin, foot, toe; far side darker and behind), parented like a skeleton with each pivot on its joint. Animate it with walk_cycle / run_cycle, or key the parts directly (rotation on a part turns it about its joint). x: hip x px (default centre); ground_y: floor line px (default 90% of the frame). hair: short | long | bob | ponytail | bun | none. colors: {skin, hair, top, bottom, shoes, line}. region / bmi: as in anatomy_reference (population averages; faces and heads are never varied by region). Every layer stays an editable vector level.

Walk a build_character rig with biomechanically correct timing for its age and sex. Feet stay planted and roll heel -> flat -> ball -> toe; legs use two-bone IK; the hips ride an inverted-pendulum arc (low at contact, high at passing); arms swing opposite the legs. Defaults come from gait studies (e.g. adult man 108 steps/min at 1.4 m/s; toddler 154 at 0.86; old age shorter steps). speed m/s, cadence steps/min override them. cycles (default 2) or end. travel=false walks in place (pan the BG). on=2 holds every pose 2 frames (keys become constant). bounce, arm_swing scale the motion (1 = natural; >1 = cartoon); lean adds forward trunk lean (deg). mood (Williams beat chart and character walks): natural | brisk | stroll (16 frames a step) | tired (20, head down, low clearance) | proud (chest out) | happy (double bounce) | sneak (crouched, 24 frames) | heavy (long contact, deep down) | cartoon (8 frames). speed/cadence still override. Returns the self-check: cadence, step length, vertical oscillation, knee flexion, foot slip.

Run a build_character rig: spring-mass physics (exact gravity in the flight phase, a spring arc in contact, lowest at mid-stance), planted feet, high knee recovery, bent arms. Defaults by age and sex from jogging norms (adult man about 166 steps/min at 3.3 m/s). Same options as walk_cycle; bounce=1 keeps gravity exact.

Convert pending vector drawings to native OpenToonz .pli levels with pen-pressure lines. Runs automatically before preview/render/open. force=true also overwrites GUI-edited levels.

Render one frame through OpenToonz and return the image (check your work visually).

Render several frames into one labelled grid (default 6 spread over the scene) to review motion.

Render with OpenToonz (tcomposer), then double-check: frame count, blank frames, flashing. format: mp4 | gif | png (sequence). shrink 2 = half size (faster drafts).

Open the scene in the OpenToonz GUI for hand editing (vector levels compiled first). After editing: SAVE in OpenToonz, then the MCP picks up your changes automatically.

Double-check a scene: structure, missing files, layer/column mapping, timing gaps, studio rule warnings (holds, pan speed), and optionally a 1-frame test render.

Record an insight from reviewing your own output (e.g. 'squash 0.8 looks rubbery; 0.4 reads better for a heavy ball'). Lessons are shown in every later scene_context so future work improves.

Store the USER's rating (1-5) and comment about a result. Ranked highest in lessons/preferences. Ask the user for this after showing a render.

Permanently adjust a style preset's defaults (learned from feedback). Keys: line, interior, wobble, wavelength, taper_start, taper_end, min_ratio, pressure_var, loop_var, exposure, squash [lo,hi], shadow, overshoot_ends. Applies to all future drawings using that style.

Search accumulated lessons (errors seen, quality issues, insights, user preferences) with advice.

Scenes known to the MCP.

Takes no parameters.

Studio looks apply_look can build from real OpenToonz fx, with what each does.

Takes no parameters.

Give the scene a studio look made of real OpenToonz fx nodes (open the FX Schematic to tweak them). look: ghibli | klaus | spider_verse | comic | anime_satsuei | painterly | cartoon_saloon (list_looks). Whole-frame fx go just before the output; per-layer fx (e.g. Klaus form shadow and rim light) go on `layers` (default: every layer except ones named like bg/background/sky). strength scales the amounts (0.5 subtle, 1 default, 1.5 strong). light_angle: degrees, 90 = light from above, 135 = top-left. Re-applying replaces the previous look; fx you made by hand are kept.

Remove the fx apply_look added (fx you made in OpenToonz stay).