spine-mcp

# spine-mcp

A Model Context Protocol server for Esoteric Software Spine 2D skeletal animation. It lets an AI assistant (Claude, Cursor, …) create, edit, validate and animate Spine skeletons without the editor running, and drives the official Spine CLI for import and export when the editor is installed.

Türkçe: README.tr.md

• 26 tools: bones, slots, attachments (region, mesh, point, bounding box, path), skins, events, IK / transform / path / physics constraints, keyframes on every Spine 4.x timeline, and rename/delete with reference cleanup.

• Writes exactly what the runtimes read. Output follows SkeletonJson from the official runtimes (value keys, inherit, drawOrder, light/dark, absolute per-channel bezier curves, and the 4.3 constraints list or the 4.2 per-type lists depending on the file's version).

• Checked against the official runtime. The test suite loads generated files with @esotericsoftware/spine-core 4.3 and checks real poses (IK, constraint mixes, path positions, easing curves).

• Easy curves: pass "ease-in-out" or a CSS-style normalized [cx1, cy1, cx2, cy2]; it is converted to Spine's absolute bezier values and keeps its shape when keys are added later.

• Safe edits: every write keeps a <file>.bak backup and returns validation problems.

• One dependency: the official mcp Python SDK (1.x and 2.x supported).

Unofficial project. Spine is a trademark of Esoteric Software LLC. This project is not affiliated with or endorsed by Esoteric Software. You need your own Spine license to use the Spine editor and CLI features.

Contents

• How it works

• Installation

• Connecting to Claude and other clients

• Tools

• Example

• Development and tests

• Limitations

Related MCP server: sky-spine-mcp

How it works

The Spine editor's own .spine project files are a binary, undocumented format. spine-mcp edits the documented Spine skeleton JSON instead, and uses the Spine CLI to move between the two:

spine_create_project("hero.json")  →  add bones, slots, attachments, constraints, animations
spine_validate("hero.json")
spine_import_data(project="hero.spine", data_file="hero.json")   # a project the editor can open
spine_export(project="hero.spine", output="export/", pack=true)  # runtime JSON/binary + atlas

Have only a .spine file? Export it to JSON first (spine_export(format="json")). Editing tools detect binary files and say so.

Installation

Requires Python 3.10+. The Spine editor is optional (needed only for spine_export, spine_import_data and spine_cli_info).

Option A: run straight from GitHub with uvx (no clone)

With uv installed, MCP clients can start the server directly:

command: uvx
args:    ["--from", "git+https://github.com/UmutFarukDilli/spine-mcp", "spine-mcp"]

Option B: clone and install

git clone https://github.com/UmutFarukDilli/spine-mcp.git
cd spine-mcp
python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -e .
# macOS / Linux
.venv/bin/python -m pip install -e .

The server command is then the venv's Python with -m spine_mcp:

Installing the package (pip install -e .) matters: MCP clients start the server from another working directory, so python -m spine_mcp must work from anywhere. Check with:

/path/to/spine-mcp/.venv/bin/python -c "import spine_mcp; print(spine_mcp.__version__)"

Spine CLI (optional)

The server finds the editor's CLI automatically (Spine.com / SpineTrial.com on Windows, Spine.app on macOS, Spine.sh on Linux, or anything on PATH). Point it at a specific install with the SPINE_CLI_PATH environment variable. Run the spine_doctor tool to see what it found.

Connecting to Claude and other clients

All clients use the same three values; examples below use Option B on Windows. Adjust the paths (or use the uvx command from Option A).

{
  "mcpServers": {
    "spine": {
      "command": "C:\\path\\to\\spine-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "spine_mcp"],
      "env": { "SPINE_CLI_PATH": "C:\\Program Files\\Spine\\Spine.com" }
    }
  }
}

env is optional.

Claude Code (CLI, or the Code tab of the Claude desktop app)

claude mcp add spine --scope user -- /path/to/spine-mcp/.venv/bin/python -m spine_mcp
# with a Spine CLI path:
claude mcp add spine --scope user -e SPINE_CLI_PATH="/Applications/Spine.app/Contents/MacOS/Spine" -- /path/to/spine-mcp/.venv/bin/python -m spine_mcp

Without the CLI, add the "spine" entry to mcpServers in ~/.claude.json (user scope, with "type": "stdio"), or to a project's .mcp.json to share it with that project.

Claude Desktop (chat)

Settings → Developer → Edit Config opens claude_desktop_config.json. Add the mcpServers block above at the top level, leaving the other settings as they are. Usual locations:

Cursor and others

Cursor reads the same block from .cursor/mcp.json. Any other MCP client: use the command, args and env above (stdio transport).

After adding it

Config is read at startup: quit the app completely and reopen it (start a new session in Claude Code). Then ask, for example, "run spine_doctor".

Tools

Discovery and validation

Creating

Constraints

Written in the file's format: the 4.3 typed constraints list (order = list position) or the 4.2 ik / transform / path / physics lists (with order).

Animating

Curve presets: linear, stepped, ease, ease-in, ease-out, ease-in-out, smooth, or a normalized [cx1, cy1, cx2, cy2]. In transform and path.mix keys, mixes you leave out keep the constraint's setup value (runtimes would otherwise treat them as 1 and switch on unused properties).

Fixing

Spine CLI (editor required)

Example

A conversation like "make a character with a waving arm" turns into calls such as:

spine_create_project(project="hero.json", name="hero", width=512, height=512)
spine_add_bone(project="hero.json", name="hip", parent="root", y=120)
spine_add_bone(project="hero.json", name="torso", parent="hip", length=80, rotation=90)
spine_add_slot(project="hero.json", name="torso", bone="torso")
spine_add_attachment(project="hero.json", slot="torso", name="torso", kind="region", width=64, height=120)
spine_set_keyframes(project="hero.json", animation="idle", timeline="rotate", target="torso",
                    curve="ease-in-out",
                    keys=[{"time": 0, "value": 0}, {"time": 1, "value": 8}, {"time": 2, "value": 0}])
spine_validate(project="hero.json")

examples/demo.json is a complete character (13 bones, 10 slots, idle / walk / wave animations, events, placeholder images in examples/images/), built by examples/make_demo.py (needs Pillow).

Development and tests

pip install -e ".[test]"
pytest

• tests/test_project.py: the document model (curves, constraints, upgrade, rename/delete)

• tests/test_validation.py: validation rules

• tests/test_cli.py: CLI detection and command building

• tests/test_stdio.py: end-to-end MCP calls over real stdio JSON-RPC

• tests/test_runtime.py: loads and poses generated files with the official Spine runtime (needs Node.js 18+ and npm ci in tools/; skipped otherwise)

cd tools && npm ci && cd ..
node tools/verify_runtime.mjs examples/demo.json                          # load + play every animation
node tools/sample_pose.mjs examples/demo.json walk 0,0.5 leg-front,hip    # bone world values

CI runs the suite on Windows, macOS and Linux with Python 3.10 and 3.13, plus mcp<2. See CONTRIBUTING.md.

@esotericsoftware/spine-core is only a development dependency for these checks; it is not bundled with or required by the server. It is covered by the Spine Runtimes License.

Limitations

• No editor GUI automation. The Spine CLI only exports, imports, packs and reports info; spine-mcp adds JSON editing on top of it.

• Binary .spine projects cannot be edited directly (see How it works). Spine 3.x JSON is refused for editing; spine_validate warns about it.

• 4.3 slider constraints are read and validated, but no tool creates them yet.

• The 4.2 constraint layout was checked by hand with spine-core 4.2; automated runtime tests use 4.3.

• CLI features need a licensed Spine editor. The Spine Trial does not export, so spine_export times out with it; the generated command can be checked with dry_run=true.

• Mesh attachments are generated as regular grids; pass uvs / vertices / triangles / hull for custom meshes, or refine them in the editor.

• CLI exports must match your runtime version (a Spine rule).

License

MIT