Spine Motion MCP

MCP server for Spine 2D animation — author, preview and export skeletal animations via natural language, from Claude Code or any MCP client.

Runs as a local HTTP server with a built-in web dashboard: each user starts the server on their own machine and connects with their own Claude account — same model as Unity MCP.

What it does

• Author animations programmatically on the documented Spine JSON format: keyframes with easing presets (easeInOut, overshoot, anticipation, …) — bezier handles are computed for you.
• Animation templates that encode animation principles: idle_breath, ui_bounce, hit_react, walk_cycle, attack_swing, celebrate, death, blink — parametric, then refine with keys_set.
• Render to GIF (preview_gif): headless Chrome + the official spine-player render any animation to an animated GIF — the agent looks at it and iterates; humans share it in chat.
• Round-trip with the Spine editor via the official Spine CLI: authored JSON → .spine project artists can open; .spine → runtime JSON + packed atlas.
• See the result: the dashboard embeds the official Spine web player. An agent can screenshot the preview page (e.g. with Playwright MCP) and iterate on what it sees.
• Mobile performance lint: bone budgets, key density, deform/clipping cost, draw-order churn, loop pops.

Requirements

• Node.js ≥ 18
• For import/export tools only: a licensed Spine editor install (the CLI ships with the editor). Authoring, lint and preview work without it.
• For preview_gif only: a Chrome-family browser (Chrome/Edge/Chromium; auto-detected, or set SPINE_MCP_CHROME). No bundled browser download.
• Spine 4.2.x (JSON format is version-coupled; pin via SPINE_MCP_EDITOR_VERSION. The embedded spine-player is pinned to 4.2.x for the same reason).

Quick start

git clone https://github.com/nihatcagri44/spine-motion-mcp.git
cd spine-motion-mcp
npm install
npm run build
SPINE_MCP_ROOT=/path/to/your/spine/assets npm start

Then connect Claude Code:

claude mcp add --transport http spine http://localhost:8734/mcp

Open the dashboard at http://localhost:8734/ — server status, skeleton browser, live animation preview.

Configuration (env vars)

Variable	Default	Purpose
SPINE_MCP_PORT	8734	HTTP port (MCP endpoint + dashboard)
SPINE_MCP_ROOT	cwd	Root directory for skeleton files (sandbox)
SPINE_MCP_CLI	auto-detect	Path to the Spine executable
SPINE_MCP_EDITOR_VERSION	4.2	Version passed to Spine CLI --update

Auto-detected CLI paths: macOS /Applications/Spine.app/Contents/MacOS/Spine, Windows C:\Program Files\Spine\Spine.com.

Tools

Tool	Needs Spine CLI	Purpose
spine_status	–	Health check, easings & templates list
skeleton_inspect	–	Bone tree, slots, skins, animations
keys_set	–	Batch keyframes with easing presets
template_apply	–	Generate an animation from a template
loop_smooth	–	Fix loop continuity pops
skeleton_lint	–	Mobile perf & hygiene checks
to_spine_project	✅	Authored JSON → .spine project
export_runtime	✅	.spine → runtime JSON + packed atlas
preview_url	–	Dashboard URL rendering the animation
preview_gif	–	Render an animation to an animated GIF (needs Chrome)

Typical agent workflow

1. skeleton_inspect — learn the rig
2. template_apply (e.g. idle_breath) — solid base
3. preview_gif → look at the GIF → evaluate motion visually
4. keys_set — refine timing/easing; loop_smooth if it loops
5. skeleton_lint — check mobile budgets
6. to_spine_project — hand off to an artist, or export_runtime → game

Status

v0.1 — early. Authoring/lint/preview are functional; CLI round-trip flags follow the official docs but are still being validated on Windows (see TESTING.md). Mesh/deform authoring and PSD→rig bootstrap are on the roadmap.

License

MIT. Spine is a product of Esoteric Software; using the Spine editor/CLI and runtimes requires a valid Spine license.