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.

Related MCP server: spine-mcp

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)

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

Tools

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.