StykAnimate MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@StykAnimate MCP open walk.styk and move the figure's left hand to (200, 150) at frame 30"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
StykAnimate MCP server
An MCP server for StykAnimate, the open-source stick figure animation app. It lets an AI assistant open a StykAnimate or Pivot project, read its rig and timeline, and change the animation — without a screen, a GPU or a browser.
The server reuses the app's own document model, rig evaluator and file codec, so a project it opens is the same project the desktop app opens, and a project it writes is the same project the app writes.
What it can do
Read a project. Open a .styk, .stkz, .stykmov, .piv or .stk file and report its
canvas, frame rate, keyframes, layers, figure definitions and instances.
Read the rig. Evaluate the animation at any tick and get back where every joint sits in canvas pixels, where each segment starts and ends, and what the inverse kinematics controllers are doing. This is the part that makes the server useful: a model can answer "where is the character's left hand at frame 30?" and act on the answer.
Change the animation. Move, rotate, scale, flip, align and re-order figures. Set a joint's
angle, length or world position. Move an inverse kinematics target. Add, delete, duplicate and
retime keyframes. Recolour figures, parts, layers and the scene. Every change is one undoable
step, and history_undo / history_redo walk back through them.
Write a project. Save as a StykAnimate project, a portable figure or a movieclip, or export
to a Pivot .piv or .stk file.
Related MCP server: Stickman Character MCP Server
The example at the top
The animation in the picture was built by asking this server to draw it, one tool call at a time. Nothing was drawn by hand and nothing was scripted against the file format.
Step | Tool |
Put the two characters, the ball and the code lines on the stage |
|
Pose them, with the arm and leg angles solved against the rig |
|
Build the timeline — fast beats at 4 ticks, slow beats at 12 to 24 |
|
Name the layers |
|
Write the file and check it |
|
The result is assets/python-vs-java.styk: 14 keyframes, 129 ticks, 24 fps, six figure definitions. It opens in the StykAnimate app like any other project.
Install
From GitHub, which needs no account and no registry:
npx -y github:ghassenTn/stykanimate-mcpPin a release:
npx -y github:ghassenTn/stykanimate-mcp#v0.1.0Or install the tarball attached to a release:
npx -y https://github.com/ghassenTn/stykanimate-mcp/releases/download/v0.1.0/stykanimate-mcp-0.1.0.tgzOr install the MCP bundle, which a client that supports one-click installs can open directly:
npx -y https://github.com/ghassenTn/stykanimate-mcp/releases/download/v0.1.0/stykanimate-mcp-0.1.0.mcpbOr clone and run it:
git clone https://github.com/ghassenTn/stykanimate-mcp.git
cd stykanimate-mcp
npm ci
node src/index.jsThe package is also prepared for the npm registry as stykanimate-mcp; see
Publishing once npm access is available.
Connect a client
Claude Code:
claude mcp add stykanimate -- npx -y github:ghassenTn/stykanimate-mcpClaude Desktop, Cursor, or any client that reads mcpServers:
{
"mcpServers": {
"stykanimate": {
"command": "npx",
"args": ["-y", "github:ghassenTn/stykanimate-mcp"]
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"stykanimate": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:ghassenTn/stykanimate-mcp"]
}
}
}Run it as a service
stykanimate-mcp --transport http --port 7331The HTTP transport speaks Streamable HTTP. It only accepts requests from localhost, 127.0.0.1
and [::1], and it rejects a request that carries a foreign Origin header, so a page in a
browser cannot drive a server that reads files from the machine. Put your own authentication in
front of it before exposing it beyond the machine.
Requirements
Node.js 20 or newer.
Python 3.10 or newer, only to read and write Pivot
.pivand.stkfiles. The server starts the bundled codec on demand and stops it again when it has been idle, so a session that only touches StykAnimate files never starts a Python process. SetSTYK_PYTHONto choose a specific interpreter.
The tools
Tool | What it does |
| What this server supports, and which projects are open. |
| Open a project file. |
| Close a project. |
| The structure of the open project. |
| Run the editor's own document validation. |
| Write the project to a file. |
| The keyframes and the playback timeline. |
| Move the playhead. |
| The figure instances in the project. |
| One figure's definition, rig and instance. |
| Add a figure instance. |
| Copy a figure, with its pose. |
| Remove a figure from keyframes. |
| Move, rotate, scale, flip, align, centre or re-order figures. |
| The solved rig at a tick. |
| Set a figure's root, scale and joint angles, lengths and positions. |
| Move an inverse kinematics target. |
| Turn a joint's inverse kinematics controller on or off, or change it. |
| Return a figure to its rest pose. |
| Add, delete, duplicate or move keyframes. |
| Change a keyframe's length, the frame rate or the canvas size. |
| The layers of the project. |
| Create, rename, delete, reorder, fill, show, hide, lock and unlock layers. |
| Recolour a figure, a part, a layer or the scene. |
| Undo the last change. |
| Redo the last undone change. |
How a model should use it
A typical conversation goes: capabilities → project_open → project_describe →
figure_describe → pose_evaluate → a change → pose_evaluate again to check the result.
Two conventions matter:
A frame number is a place on the timeline — one of the positions the playhead moves through. The pose and figure tools use it, because they act on what the animation shows. The "playback" section of
project_timelinelists those places, and their number is the frame number.A keyframe number in
keyframe_editandkeyframe_timingis a stored pose, one entry in the project's pose list, because those tools add, remove and retime poses. The "keyframes" section ofproject_timelinelists those, and says where each one is shown.
On a project with one keyframe per moment the two are the same number, which is the case for every project imported from Pivot. A project with an advanced timeline can hold more poses than it shows, and there the two differ: a pose the playback does not reach has no place, and only the keyframe tools can name it.
A figure is named by its instance id, and a joint by its handle id. Both come from
figure_list and figure_describe.
Projects with an advanced timeline
StykAnimate has two timelines. The simple one is a list of keyframes, each holding the pose of every figure, and it is what a project imported from Pivot uses. The advanced one is a sheet of cells that sample stored poses over spans, and it is what the app's own new projects use.
The server works on the stored poses the playback reaches. The sheet's own cells are not exposed, so a few results differ from the app:
figure_listreports the figures the sheet shows at the playhead, and lists the stored poses that hold each of them. A figure the sheet added appears in the first list and in none of the second.The pose and figure tools act on the place they are given, so they change what the sheet shows.
style_seton a figure names the ticks the playback reaches, because that is what a sheet holds.A keyframe the playback does not reach can still be added, retimed and removed through the keyframe tools, but nothing shows it.
project_describereportsadvancedTimeline: truewhen a project uses one.
Everything else — opening, describing, transforming, recolouring, saving — behaves the same in both.
Resources
Resource | What it holds |
| A summary of every open project. |
| The whole editable document. |
| The solved rig at a tick. |
How it is built
src/ The server: tools, session, file I/O and the codec client
src/tools/ One module per group of tools
vendor/ The StykAnimate editor core, vendored from the app
py/ The Python codec, vendored from the app
scripts/ The vendor sync and the package checks
test/ The testsvendor/stykanimate holds the transitive import closure of the app's editor.mjs,
native-container.mjs and friends: about 300 modules with no third-party runtime dependencies.
scripts/vendor-sync.mjs refreshes it from a checkout of the app and records what it copied in
vendor/stykanimate/PROVENANCE.json. npm run vendor:check fails when the vendored copy has
drifted from its source.
The sync looks for the app in a sibling StykAnimate-App directory by default. Point it
elsewhere with --source <path> or the STYKANIMATE_SOURCE environment variable:
npm run vendor -- --source ../StykAnimate-AppDevelopment
npm ci
npm run check # syntax, tool registration, vendored-core freshness, registry manifest
npm test # the test suitenode scripts/demo-session.mjs drives the server over stdio the way a client does and prints
every answer, which is the quickest way to see the whole flow: open, describe, pose, time,
recolour, undo, save and reopen.
The tests need a Python interpreter for the codec test; that one test skips itself when there is none.
Publishing
The package is prepared for the npm registry as stykanimate-mcp.
npm ci
npm run check && npm test
npm run publish:packageprepublishOnly runs the checks and the tests, so a publish cannot ship a broken package. The
version in package.json and the one in server.json have to move together, because the
registry manifest names the exact package version.
A tagged release publishes the package again with provenance:
git tag v0.1.0 && git push origin v0.1.0The workflow needs an NPM_TOKEN secret in the repository settings.
The MCP bundle
npm run bundle builds build/stykanimate-mcp-<version>.mcpb: a zip archive with the server,
its runtime dependencies, the vendored editor core, the Python codec and a manifest that tells a
client how to run it. It is the package type the official MCP registry accepts without a package
registry, and clients that support one-click installs can open it directly.
The bundle's hash goes in server.json under packages[0].file_sha256, so the registry and a
client can both check the file they download. The build writes the hash next to the bundle:
npm run bundle
cat build/stykanimate-mcp-0.1.0.mcpb.sha256Until npm is available, the release tarball and the bundle are the installable artifacts: they are the same package the registry would serve, and they are attached to every release.
Licence
GPL-3.0-or-later, the same licence as the StykAnimate app this server is built from. See LICENSE and NOTICE.md.
Available Tools
26 toolscapabilitiesWhat this server can doARead-onlyIdempotent
Report what this server supports: the file formats it can read and write, whether the Python codec for Pivot files is available, and the projects that are currently open. Call this first when you do not know what the project looks like yet.
Inputs: no named parameters.
figure_addAdd a figureA
Add a figure instance to the keyframe the playhead is on, using one of the existing figure definitions. The new figure is placed at the given position, or at the centre of the canvas. Give a keyframe number to choose the keyframe; without one the playhead decides. Give the definition to use with "figureTypeId"; omit it to use the first definition in the project.
Inputs: x, y, frame, project, +1 more.
figure_deleteRemove a figureADestructiveIdempotent
Remove a figure from a keyframe. Figures joined to it are detached and kept. Give "frames" to remove it from several keyframes at once.
Inputs: uid (required), frame, frames, project.
figure_describeDescribe a figureARead-onlyIdempotent
Report one figure in full: its definition (every joint with its handle id, parent, length, angle, thickness, shape and colour), its fills, its rig, and where it sits in a keyframe. Name an instance with "uid", or a definition with "figureTypeId".
Inputs: uid, frame, project, figureTypeId.
figure_duplicateDuplicate a figureA
Copy a figure, including its pose, into a keyframe. Give a keyframe number to choose it; without one the playhead decides. The copy is nudged by an offset so it does not sit exactly on the original. The copy gets a new id.
Inputs: uid (required), frame, offset, project.
figure_listList figuresARead-onlyIdempotent
List the figure instances the animation shows, with their ids, names, layers, position, scale, opacity and colour, and the stored keyframes that hold them. Give a keyframe number to list the figures at that moment; without one the playhead decides. Use the ids this returns with the other figure and pose tools.
Inputs: name, frame, layer, limit, +1 more.
figure_transformTransform a figureA
Change where a figure sits: move it, rotate it, scale it, flip it, align it with other figures, centre it, or change its draw order. Angles are in degrees and turns anticlockwise. Give "uids" to transform several figures in one step; they move together.
Inputs: action (required), dx, dy, uid, +9 more.
history_redoRedoAIdempotent
Redo the change that was last undone in the open project.
Inputs: project.
history_undoUndoADestructiveIdempotent
Undo the last change to the open project. Every tool that changes a project makes one undoable step, so one call reverses one tool call. Repeat the call to undo further changes.
Inputs: project.
keyframe_editEdit keyframesADestructive
Change the shape of the timeline: add a keyframe, delete keyframes, duplicate them, or move one to a different position. A keyframe holds the pose of every figure at that moment, so adding one copies the current pose. A keyframe number here is a stored pose, which is what the file keeps. Give "frames" to act on several keyframes at once.
Inputs: action (required), to, blank, frame, +2 more.
keyframe_timingChange the timingAIdempotent
Change how long the animation runs: the length of a keyframe, the frame rate of the whole project, or the size of the canvas. A keyframe length is in ticks; at 24 fps a length of 24 is one second. A keyframe number here is a stored pose, which is what the file keeps.
Inputs: action (required), fps, frame, ticks, +4 more.
layer_editEdit layersADestructive
Change the layers of the project: create one, rename one, delete one, reorder them, move figures between them, or show, hide, lock or unlock one. Give the action and the fields it needs.
Inputs: action (required), name, uids, index, +5 more.
layer_listList layersARead-onlyIdempotent
List the layers of the open project, with their ids, names, visibility, lock state and the figures each one holds. Use the layer ids this returns with layer_edit and figure_transform.
Inputs: project.
pose_evaluateEvaluate the rigARead-onlyIdempotent
Read the solved rig at a point in the animation: where every joint sits in canvas pixels, where each segment starts and ends, and what the inverse kinematics controllers are doing. Use this to find out where a hand or foot is before changing it, and to check a pose after changing it. Give a tick for sub-keyframe precision, or a keyframe number.
Inputs: tick, uids, frame, project, +1 more.
pose_ik_setMove an IK targetA
Move the inverse kinematics target of a joint, placing a hand or foot at a point on the canvas. The controller must already be enabled on that joint; use figure_describe to see which joints have controllers. A pinned controller keeps the target when the figure moves; an unpinned one bakes the pose.
Inputs: x (required), y (required), uid (required), handleId (required), +2 more.
pose_resetReset a poseAIdempotent
Return a figure to the rest pose of its definition, dropping the angles, lengths and bends it had. The figure keeps its position, size and colour.
Inputs: uid (required), frame, frames, project.
pose_setSet a poseA
Change a figure's pose in one keyframe: move its root, scale it, and set the angle, length or world position of any of its joints. A joint is named by its handle id (from figure_describe) or by its index in the segment list. An angle is absolute, measured from the parent joint, in radians or degrees. Give a world x and y to place a joint at a point instead; that respects inverse kinematics. Everything in one call is a single undo step.
Inputs: uid (required), root, frame, scale, +2 more.
pose_set_ikConfigure an IK controllerA
Turn the inverse kinematics controller of a joint on or off, pin or unpin its target, allow it to stretch, or change how many bones its chain covers. Enabling a controller creates it at the joint's current position, so the pose does not jump.
Inputs: uid (required), handleId (required), frame, pinned, +5 more.
project_closeClose a projectADestructiveIdempotent
Close an open project and release its editor. Unsaved changes are discarded; save first with project_save.
Inputs: project.
project_describeDescribe the projectARead-onlyIdempotent
Report the structure of the open project: canvas, frame rate, keyframes, figure definitions and instances, layers, backgrounds, effects, movieclips and audio. Ask for the parts you need with the "include" list; without it the tool returns the summary alone.
Inputs: limit, include, project.
project_openOpen a projectARead-onlyIdempotent
Open a StykAnimate or Pivot project file and make it the active project. Accepts .styk, .stkz and .stykmov (StykAnimate native files, read directly in JavaScript) and .piv and .stk (Pivot files, read through the bundled Python codec). Returns a project id that later tools accept, plus a summary of the project. Opening a file does not change it.
Inputs: path (required).
project_saveSave the projectADestructive
Write the open project to a file. Use "styk" for a StykAnimate project, "stkz" for a single figure, "stykmov" for a movieclip, and "piv" or "stk" for Pivot files (these need the Python codec). A figure file holds one figure: name it with "figureTypeId" or "figureUid", or leave both out to take the first figure in the project. The file is written in full before it replaces the destination, so a failure leaves the previous file intact. Give a path to choose where it goes, or leave it out to save beside the file it was opened from.
Inputs: path, format, project, figureUid, +1 more.
project_seekMove the playheadARead-onlyIdempotent
Move the editor's playhead to a keyframe or an absolute tick. The playhead decides which keyframe later tools edit when no frame is named.
Inputs: tick, frame, project.
project_timelineShow the timelineARead-onlyIdempotent
List the timeline of the open project. The "playback" section is the list of places the playhead moves through: their number is the frame number the pose and figure tools take. The "keyframes" section is the list of stored poses, with the place each one is shown at. Give "fromTick" and "toTick" to narrow the playback list.
Inputs: limit, toTick, project, fromTick.
project_validateValidate the projectARead-onlyIdempotent
Run the editor's own document validation over the open project and report the first problem it finds, or confirm that the project is valid. Use this after edits that a client rejected, and before saving.
Inputs: project.
style_setChange appearanceAIdempotent
Change how something looks: the colour or opacity of a figure, the colour or thickness of one of its parts, the colour of a layer, or the colour behind the scene. A figure colour applies to every keyframe the figure appears in. A part colour changes the shared figure definition, so every instance of it changes too. Give a colour as "#rrggbb" or as three red, green and blue bytes.
Inputs: target (required), uid, color, frame, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools target a clear resource+operation, but `pose_ik_set` (move an IK target) and `pose_set_ik` (toggle/pin the IK controller) differ only by word order and will be misselected constantly. `pose_set` also overlaps with `pose_ik_set` since it can place a joint at a world position respecting IK, and `style_set` bundles figure, part, layer and background colouring that partly overlaps `layer_edit` and `figure_transform`.
Nearly all 26 tools follow a noun_verb pattern (layer_list, project_open, figure_delete, keyframe_edit, pose_reset), which is predictable. The lone bare `capabilities` and the near-anagram `pose_ik_set`/`pose_set_ik` pair are the only deviations worth noting.
26 tools sits just above the well-scoped band for a single animation editor, and several verbs are split across many narrow tools (six figure_*, six pose_*, two keyframe_*). It is defensible for a project/rig/timeline editor, but the surface feels heavy and some tools could be consolidated.
Core lifecycle is covered: open/close/save/validate/describe, undo/redo, layers, figures, poses, keyframes, timing and styling. But there is no tool to create or edit figure definitions/joints, no tool to edit effects, backgrounds or movieclips despite project_describe reporting them, and no render/export operation — notable dead ends for an animation tool.
Maintenance
Related MCP Connectors
Create AI animations and export transparent sprite sheets, alpha video, frames, and game assets.
Open-source AI video editor: cut, caption, clip and animate real Revline projects from your agent.
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
Screenplay and storyboard in your AI assistant: import scripts, edit scenes, build shots.
Related MCP Servers
FlicenseNot gradedqualityCmaintenanceEnables AI assistants to browse, inspect, edit, create, and export SVGator projects, handling everything from simple color edits to complex animated exports.5-- FlicenseNot gradedqualityDmaintenanceEnables MCP-compatible coding agents to control a posable, rigged stickman character by setting joint angles and facial expressions, and to render still frames or full animations as SVG, PNG, GIF, or MP4.-
- AlicenseAqualityBmaintenanceEnables AI assistants to create and edit layers, set attributes and keyframes, wire connections, render PNG previews, and save scenes in the 2D procedural motion-design application through typed, validated tools.29MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to turn a plain scene description into a stick-figure animation — complete with walks, props, poses, physics-timed arcs and audio — and export it as MP4, WebM or GIF, or save it as an editable project file. Frames are rendered headlessly by the real animation app, so output matches the app's own exporter.46 npm3GPL 3.0