spine-mcp — Spine 2D animation MCP server

Make production Spine 2D animations from a cut-up character — straight from a .psd or a PhotoshopToSpine export folder. Inspired by ampersante/spine2d-animation-mcp, but it ships real runtime rigs that play in spine-pixi / pixi games and editable .spine projects (via the licensed Spine 4.3 CLI), with hand-crafted motion instead of canned templates.

cut parts (you, in Photoshop)            ──▶  rig_and_animate
  PSD  or  PhotoshopToSpine export             │
                                               ├─▶ <name>.json   runtime skeleton (Spine 4.2)
                                               ├─▶ <name>.atlas + .png   packed atlas
                                               └─▶ <name>.spine  EDITABLE project (open in your Spine)
                                          ──▶  preview (montage PNG)  /  wire into the game

Why it beats the original

	ampersante MCP	spine-mcp (this)
Rig	auto by layer name	bones placed at joints, head/body hierarchy
Motion	predefined templates	hand-authored idle/win/blink/pop, squash-stretch, face-swap
Atlas	Pillow	real Spine CLI packer
Output	JSON / PNG / GIF preview	runtime rig that runs in the game + editable .spine
Head states	drawn stacked	collapsed to one slot, swapped in win/blink

Tools

• spine_doctor — check Spine CLI + Python deps
• inspect_source — list parts / detected head-state families before rigging
• rig_and_animate(source, out_dir, name?, kind?, anims?, make_editable?) — the main one
• pack_atlas(images_dir, out_dir, name) — Spine-CLI atlas pack
• make_project(runtime_json, out_spine) — runtime json → editable .spine
• export_project(project, out_dir, fmt) — .spine → runtime json+atlas
• project_info(project_or_json) — bones/slots/animations
• preview(rig_dir, images_dir?, out_png?, maxpx?) — keyframe-montage PNG
• batch(roster_dir, out_root, kind?, make_editable?) — rig every export subfolder

Input conventions

• Head-state family: name the alt faces <base>_win / <base>_blink (e.g. head, head_win, head_blink, or face, face_win, face_blink). They auto-collapse into one slot and swap inside win / blink.
• Glow layer named Layer 2 → additive blend + pulse. Parts named *fire* → flicker. Parts named *rot* → spinning accent bone.
• Leave a small overlap tab on each part under its joint so bends don't tear.

Install

The easy way, alongside the brain that knows how to use it:

/plugin marketplace add egorfedorov/mozg-plugin
/plugin install mozg-spine@mozg

Or wire it up directly — needs uv:

claude mcp add spine -- uvx --from git+https://github.com/egorfedorov/spine-mcp spine-mcp

From a checkout, for hacking on it:

uv venv && uv pip install -e .
./.venv/bin/spine-mcp          # stdio MCP server

Your Spine licence stays yours

This project contains no part of Spine and grants no licence to it. Spine is commercial software from Esoteric Software, and everyone runs their own installation under their own licence. The server looks for it at /Applications/Spine.app/Contents/MacOS/Spine, or wherever SPINE_BIN points.

It works without one. Rigging and animating never start a Spine process — they are plain Python over Pillow and psd-tools. A licence adds three tools:

	needs Spine
rig_and_animate — skeleton, animations, atlas	no
inspect_source, preview	no
pack_atlas — the Spine packer	yes
make_project / export_project — editable .spine	yes
project_info	yes

spine_doctor reports what it found. One person's licence never reaches another, and nothing degrades because somebody else has a different one.

Naming conventions it assumes

_classify decides what is a head from a word list tuned on one studio's art — head, face, golova, crown, tooth. A layer called kopf or cabeza lands in the body instead. Override it rather than renaming your art:

export SPINE_HEAD_WORDS="kopf,gesicht,krone"

Files

• server.py — FastMCP server (tool surface)
• spine_rig.py — rig + animation builder (pure, importable, runnable standalone)
• spine_cli.py — Spine 4.3 CLI wrappers (pack / import / export / info)
• spine_preview.py — keyframe-montage renderer

Licence

MIT — see LICENSE. Written for, and used by, mozg's Spine 2D Animation brain, which is the half that knows how the rigs should move.