Skip to main content
Glama

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

Related MCP server: spine-mcp

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.

Available Tools

9 tools
batchB

Rig every PhotoshopToSpine export subfolder under roster_dir into out_root//. Returns per-character summaries.

Inputs: out_root (required), roster_dir (required), kind, make_editable.

export_projectB

Export a .spine project to runtime files (fmt: json|binary, +pack for atlas).

Inputs: out_dir (required), project (required), fmt.

inspect_sourceA

List the parts and detected head-state families of a .psd or a PhotoshopToSpine export folder, WITHOUT building anything. Use this first to confirm what will be rigged.

Inputs: source (required).

make_projectB

Import a runtime skeleton json into an EDITABLE .spine project.

Inputs: out_spine (required), runtime_json (required).

pack_atlasB

Pack a folder of PNGs into .atlas + .png with the Spine packer.

Inputs: name (required), out_dir (required), images_dir (required).

previewB

Render a keyframe-montage PNG of a built rig (idle/win/blink/pop poses).

rig_dir folder holding .json (the out_dir from rig_and_animate) images_dir folder with the part PNGs (defaults to the source export images) out_png output path (defaults to <rig_dir>/_preview.png)

Inputs: rig_dir (required), maxpx, out_png, images_dir.

project_infoB

Print bones/slots/animations of a .spine project or skeleton .json.

Inputs: project_or_json (required). Returns: result

rig_and_animateA

Build a rigged + animated Spine skeleton from a cut-up character.

source path to a .psd OR a PhotoshopToSpine export folder out_dir where to write .json/.atlas/.png (e.g. a game's static/assets/spine//) name skeleton name (defaults to the source basename) kind "symbol" or "mascot" (reserved; both rig the same body+head now) anims subset of ["idle","win","blink","pop"] (default all applicable) make_editable also emit an editable .spine next to the source (Spine CLI)

Returns a summary incl. file paths and an editable-project path.

Inputs: source (required), out_dir (required), kind, name, +2 more.

spine_doctorA

Report whether the Spine CLI and Python deps are available.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct action: packing, project creation, export, info, preview, batch, environment check, source inspection, and rigging. No two tools overlap in purpose.

    Naming Consistency3/5

    Tool names mix conventions: some verb_noun (pack_atlas, make_project), some nouns (project_info, spine_doctor), and single verbs (preview, batch). This inconsistency makes the set less predictable, though still readable.

    Tool Count5/5

    9 tools is well-scoped for a Spine workflow server, covering creation, conversion, inspection, preview, and batch operations without bloat.

    Completeness5/5

    The server covers the full lifecycle from source inspection and rigging to atlas packing, project conversion, info, preview, and batch processing. No obvious missing operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local MCP server for automating Spine projects via the official CLI, enabling AI tools to inspect, export, import, and add animations to .spine files.
      16
      25
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that converts layered PSD characters into Spine 4.2 rigs with deterministic, parametric 2D/2.5D animations (idle, walk, run, jump, attack, hit) ready for the Spine editor and Unity.
      4
      5
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      MCP server for reading, validating, and modifying Spine 4.1.24 JSON animation files, with tools for animation timeline editing, validation, preview, and agent integration.
      36
      -