StykAnimate MCP

An MCP server that lets an AI assistant make stick-figure animations with StykAnimate and export them as video — for example a 1080 × 1920 YouTube Short — from a plain scene description. It runs the real StykAnimate app headless, so every frame comes from the app's own renderer and exporter, and the saved .styk project opens in the app for hand editing.

Install

Claude Code:

claude mcp add stykanimate -- npx -y github:mashhoorahdal/stykanimate-mcp

Any other agent, or several at once:

npx -y github:mashhoorahdal/stykanimate-mcp install            # list agents and which are installed
npx -y github:mashhoorahdal/stykanimate-mcp install all        # every agent found
npx -y github:mashhoorahdal/stykanimate-mcp install codex cursor

Options: --output <dir> for videos (default ~/styk-videos), --name <name>, --dry-run, and remove instead of install to unregister. Config files are edited in place, keeping their other entries.

Any MCP client can also run npx -y github:mashhoorahdal/stykanimate-mcp as a stdio server.

Animation skills

Two skills teach an agent to animate well with these tools:

• stykanimate-natural-motion: acting and timing for human-like motion. It covers beat sheets, holds, anticipation, overshoot, overlap, talking, reacting, handing things over, walking and shots for Shorts, plus a review checklist.

• stykanimate-physics: gravity, weight, momentum, balance and contact. It covers jumps, throws, catches, drops, bounces, heavy lifting and falls, using physics_plan and arc.

Every MCP client gets them as the prompts natural-motion and physics (in Claude Code: /mcp__stykanimate__natural-motion). To install them as skills that load automatically:

npx -y github:mashhoorahdal/stykanimate-mcp skills all      # ~/.claude/skills and ~/.agents/skills
npx -y github:mashhoorahdal/stykanimate-mcp skills claude   # Claude Code only (opencode reads it too)
npx -y github:mashhoorahdal/stykanimate-mcp skills agents   # Codex, opencode and other ~/.agents/skills readers

--dir <path> copies them somewhere else; --remove uninstalls them.

Related MCP server: Stickman Character MCP Server

Requirements

• Node.js 22 or newer.

• Python 3.11 or newer, which runs StykAnimate's codec service (STYK_PYTHON picks the interpreter).

• Google Chrome for direct MP4 export. Without it, Playwright's Chromium is downloaded once (about 150 MB) and MP4s are made from WebM with ffmpeg.

• ffmpeg for MP4 with sound, and for MP4 without Chrome. WebM and GIF never need it.

The first start downloads StykAnimate's source (about 16 MB) into your cache folder. To do that ahead of time, together with the browser check: npx -y github:mashhoorahdal/stykanimate-mcp prepare.

What it can do

A spec lists the cast once (stickmen with optional eyes, rectangles, lines, circles, captions and Pivot .stk figures), then keyframes that only say what changes. Motion between keyframes tweens with the app's easing. Natural motion is built in:

• walk keyframes expand into a stride-matched walk or run cycle that faces the way it goes.

• attach holds a prop in a hand with an app join, so it follows every frame and can be handed over.

• bend and turn pose joints relative to their parent bone (forward kinematics).

• overshoot swings past a pose and settles; still pauses on a pose before the next move.

• arc moves a figure along a gravity parabola into a keyframe, sampled smoothly while the rest of the scene keeps moving; physics_plan picks heights and flight times that match real gravity.

• face turns the eyes to the viewer or sideways; about forty named poses cover talking, reaching, knocking, picking up, sitting and more.

• Voiceover and music files can be placed on the timeline, and the animation stretches to fit them.

examples/grocery-run.json is a complete 24-second Short: a man walks to a shop, orders, pays and carries his groceries home.

Configuration

How it works

src/spec.mjs compiles a spec into a native StykAnimate document with the app's own document factories and validates it with the app's scene validator. src/session.mjs starts the app's codec service and a headless browser on the app, loads the document into the editor and drives the app's export dialog and Save As, so exports match what the app produces. src/app.mjs downloads the pinned app source once; src/browser.mjs finds or installs a browser. The server answers its client's handshake immediately and loads the app on the first tool call.

Development

npm ci
npm test            # spec compiler unit tests (downloads the app on first run)
npm run smoke       # build, preview, save and export examples/hello-short.json into out/smoke
npm run test:mcp    # a full stdio round trip with sound; needs ffmpeg

License

GPL-3.0-or-later. This server runs and builds on StykAnimate (GPL-3.0-or-later), which it downloads at run time; it is not affiliated with the StykAnimate project.