GPT Spine MCP
Build, validate, preview, and export Spine 2D rigs and animations from PSD or PhotoshopToSpine sources, with optional licensed Spine CLI integration.
Diagnose Spine CLI and Python dependencies with
spine_doctor.Inspect PSDs or export folders for parts and head-state families with
inspect_source.Rig and animate characters with mesh cleanup, auto weights, IK, clipping, slot presets, and FX presets via
rig_and_animate.Run the complete production workflow through rigging, animation, save/export, preview, validation, and
rig_report.jsonwithbuild_workflow.Compile authored numeric motion specs and audit frame grids, handoffs, and loop seams with
apply_motion_specandvalidate_motion.Validate bones, slots, skins, IK, atlas, texture, and animation references with
validate_output.Render keyframe montage previews and reject blank/static previews with
previewandaudit_preview.Pack atlases, create editable
.spineprojects, export runtime files, and inspect project info withpack_atlas,make_project,export_project, andproject_info.Batch-process rosters of PhotoshopToSpine exports with
batch.
Provides an OpenAI Agents SDK client that launches the MCP server over stdio and runs natural-language production requests through an OpenAI agent; also supports Codex MCP registration.
Integrates with a licensed Spine CLI to pack textures into atlases, create editable .spine projects from runtime JSON, export runtime output, inspect Spine projects, and generate editable Spine 2D rigs and animations when the CLI is available.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GPT Spine MCP Rig mega_win.psd with clean meshes, auto-weight, IK, and intro/celebration animations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GPT Spine MCP
OpenAI/Codex tooling for turning a layered PSD or PhotoshopToSpine export into a
validated Spine 2D rig, animation set, atlas, preview, and—when a licensed Spine
CLI is installed—an editable .spine project and runtime export.
This project is based on
egorfedorov/spine-mcp and keeps the
original MIT licence and server tools. It removes the Claude-only setup path,
adds a production CLI, exposes a complete MCP workflow, and includes an OpenAI
Agents SDK client.
What it produces
mega_win.spine # when the licensed Spine CLI is available
mega_win.atlas
mega_win.png
mega_win.json
rig_report.json
preview/
montage.png
export/ # optional Spine CLI exportThe pure-Python rig, atlas, runtime JSON, validation report, and preview work without Spine. Spine is commercial software and is not bundled or licensed by this project.
Related MCP server: Spine Motion MCP
One-command local install
From a checkout on macOS or Linux:
./scripts/install.shThat installs gpt-spine, gpt-spine-mcp, and the optional OpenAI Agents SDK
with uv. Pass --codex to also register the local stdio MCP server:
./scripts/install.sh --codexOn Windows PowerShell:
.\scripts\install.ps1
.\scripts\install.ps1 -Codex # also register the stdio server with CodexFor an immutable release, replace the URL below with the published fork and pin the tag:
uv tool install "gpt-spine-mcp[agents] @ git+https://github.com/kumikilongyeyo/gpt-spine-mcp@v0.7.1"
codex mcp add gpt-spine -- gpt-spine-mcpCommand line workflow
gpt-spine rig mega_win.psd \
--source-group "mega win" \
--clean-mesh \
--auto-weight \
--ik \
--clipping \
--slot-presets pulse,flash,flicker \
--fx-presets coin_splash,glow_flash,particle_explosion,bomb_explosion,fire,splash,clipped_shine \
--animations intro,steering,wave,mega_win,celebrationUseful modes:
# Skeleton, atlas, and validation only—no animation timelines.
gpt-spine rig character.psd --rig-only
# Keep runtime output independent of the licensed editor.
gpt-spine rig character.psd --no-editable --no-export
# Check which Spine executable was auto-detected.
gpt-spine doctor
# Reject a blank/static preview and compare it with an art-direction reference.
gpt-spine audit-preview build/mega_win.gif --reference art-direction.gifSPINE_BIN has priority when set. Otherwise macOS detection checks the normal
app bundle, user Applications, Setapp, versioned bundles, and PATH. Windows
checks Spine.com first (the console executable recommended for CLI use), then
Spine.exe, under Program Files, Program Files (x86), LocalAppData, and PATH.
Linux checks ~/Spine/Spine.sh, /opt/Spine/Spine.sh, and PATH.
OpenAI Agents SDK client
Set OPENAI_API_KEY, then give the agent a natural-language production request:
gpt-spine agent "Inspect ./mega_win.psd, build a clean weighted rig with IK, generate intro and celebration, and validate it"The client launches this repository's MCP server over stdio with
MCPServerStdio, attaches it to an OpenAI Agent, and runs the request through
the Agents SDK. Use only trusted MCP servers and review actions that touch
licensed projects or production assets.
MCP tools
build_workflow— complete rig → animation → save/export → preview → validate flowspine_doctor— dependency and Spine CLI diagnosisinspect_source— layer, part, and head-state inspectionrig_and_animate— lower-level rig builder with mesh/weight/IK/clipping optionsvalidate_output— semantic runtime/atlas validationpack_atlas— licensed Spine CLI texture packingmake_project— runtime JSON to editable.spineexport_project—.spineto runtime outputproject_info— licensed CLI project inspectionpreview— fast keyframe montageaudit_preview— objective blank/static/duration/motion/occupancy delivery gateapply_motion_spec— compile model-authored numeric clips with named easing curvesvalidate_motion— frame-grid, intro→loop handoff, and loop-seam auditbatch— process a roster of PhotoshopToSpine exports
Rig and animation behavior
--clean-meshconverts regions to non-degenerate four-corner meshes.--auto-weightwrites single-bone weighted vertices as an editable baseline.--ikadds a target and constraint for the head, or body when no head exists.--clippingadds a full-rig bounds clip that can be reshaped in Spine.Known state names (
intro,steering,wave,mega_win,celebration) get tailored starter timelines. Any other state gets a safe neutral motion instead of being dropped.Slot presets (
pulse,flash,flicker) are separate animations suitable for mixing on another track.Head variants named
<base>_winand<base>_blinkcollapse into one slot and use attachment timelines.
These are deterministic production starters, not an art-director replacement. Mesh topology, weights, constraint targets, and clipping shapes should still be reviewed on hero assets.
Authored motion workflow
The MCP does not pretend a preset name can understand art direction. For hero
animation, the agent first inspects the actual bones and slots, translates the
description into a numeric JSON motion spec, and calls apply_motion_spec.
Supported named curves are out, in, inout, sine, outback, and expo.
validate_motion then checks frame alignment, exact intro→loop handoffs, and
loop seams before the editor import/render step.
FX packs are mixable independent animations: fx_coin_splash,
fx_glow_flash, fx_particle_explosion, fx_bomb_explosion, fx_fire, and
fx_splash, plus fx_clipped_shine. They use additive white-on-alpha light assets, staggered bones,
overshoot/follow-through, source coin artwork when available, and authored
Bezier curves. FX are invisible in the setup pose, alpha is snapped to the
runtime's 8-bit precision, and clipped shine derives its mask from the target
art's alpha silhouette. Procedural fire/smoke are blocking FX; painterly hero effects
should still be supplied as art and driven by the same motion-spec compiler.
Editable .spine files do not embed bitmaps. Always deliver the project beside
its images/ folder. GPT Spine copies every source and generated image into the
final output before import and fails portability validation if any are missing.
Input conventions
A PhotoshopToSpine directory needs a layout JSON containing skins and an
images/ directory. PSD import walks visible nested leaf layers, assigns unique
attachment names, and reports semantic role guesses. Use --source-group when
the intended asset set is inside a named folder; this prevents unrelated PSD
concepts from being flattened into the rig. The
default head classifier recognizes head,face,golova,crown,tooth; override it:
export SPINE_HEAD_WORDS="kopf,gesicht,krone"Development and verification
uv sync --extra dev --extra agents
uv run pytest
uv run gpt-spine doctorThe macOS, Windows, and Linux CI jobs build a synthetic character end to end, assert rig-only behavior, verify mesh weights, IK, clipping, state generation, slot presets, reports, and preview output. Tests do not require a Spine licence or OpenAI API key.
Release line
Version | Scope |
| upstream MCP rig/animation foundation |
| PSD import and rig workflow |
| mesh, weights, and constraints |
| multi-state animation generation |
| slot FX, clipping, validation, OpenAI/Codex client |
| macOS/Windows/Linux installers and cross-platform CI |
| nested PSD groups, semantic inspection, reference preview QA, portable image checks |
| package QA module and install PSD composite dependencies |
| numeric motion-spec compiler, curve/seam validation, and mixable FX packs |
| setup-hidden FX, byte-snapped alpha, and alpha-silhouette clipped shine |
| planned stable workflow after real-asset compatibility testing |
Never move a published tag. Patch a release and add a new tag so a known-good production build remains reproducible.
Licence
MIT. See LICENSE. Original work copyright remains with its author;
new contributions remain under the same licence.
Available Tools
14 toolsapply_motion_specA
Compile an explicit numeric motion spec into a Spine skeleton.
Inspect the source/project first, translate art direction into timed bone and slot tracks with named eases, then call this tool. Specs contain fps, clips, optional handoffs, and bone/slot keys. This validates target names, curve generation, frame alignment, intro→loop handoffs, and loop seams.
Inputs: out_json (required), motion_spec (required), runtime_json (required).
audit_previewB
Reject blank/static previews and compare duration, motion, and occupancy against an optional art-direction reference before a delivery is accepted.
Inputs: preview_gif (required), reference_gif.
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.
build_workflowB
Run the complete production workflow: rig, animate, mesh/weight, add optional IK and clipping, save/export when Spine is installed, render a preview, and write rig_report.json. Set rig_only for a zero-animation rig.
Inputs: source (required), out_dir (required), ik, name, +10 more.
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), source_group.
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), ik, kind, +9 more.
spine_doctorA
Report whether the Spine CLI and Python deps are available.
Inputs: no named parameters.
validate_motionC
Audit authored clips for frame-grid, curve, handoff, and loop-seam errors.
Inputs: runtime_json (required), clips, handoffs.
validate_outputC
Validate bone, slot, skin, IK, atlas, texture, and animation references.
Inputs: runtime_json (required), atlas, texture.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have clearly distinct purposes (inspect_source vs rig_and_animate vs apply_motion_spec vs pack_atlas). The main overlap is build_workflow, which subsumes rig_and_animate plus mesh/clip/export steps, so an agent may be unsure whether to use the atomic tool or the all-in-one pipeline. The validation trio (audit_preview, validate_motion, validate_output) is distinguishable by target but close enough to require care.
The set mostly follows a verb_noun snake_case pattern (inspect_source, rig_and_animate, apply_motion_spec, validate_motion, pack_atlas, make_project, export_project). A few deviations exist — spine_doctor and project_info are noun-first, while preview and batch are bare. Still readable and largely predictable.
14 tools for a full rig/animate/validate/export pipeline is reasonable and most earn their place as distinct pipeline stages. It sits at the higher end but does not feel redundant given the breadth of the workflow.
The surface covers the full lifecycle: environment check (spine_doctor), inspect, rig/animate, motion-spec authoring, mesh/IK/clip validation, atlas packing, editable project round-tripping (make_project/export_project/project_info), preview rendering, batch roster processing, and quality gating. No obvious dead ends.
Maintenance
Related MCP Connectors
Build editable 3D scenes, direct characters and cameras, and export AI video references with MCP.
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Split character art into named layers and export PSDs for Live2D and Spine.
Render Spine 3.8 skeleton animations to PNG frames or GIF. Pay per call with points.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.45MIT
- AlicenseNot gradedqualityDmaintenanceEnables authoring, preview, and export of Spine 2D skeletal animations via natural language from Claude Code or any MCP client, with a web dashboard and tools for keyframing, templates, and GIF preview.8MIT
- FlicenseBqualityBmaintenanceEnables any MCP client to turn layered PSD artwork into game-ready Spine packages by inspecting and classifying layers, rigging with meshes, bones, weights, IK, physics and animation, applying procedural or After Effects-driven FX, and running runtime and mobile-budget validation with preview output. It finishes by exporting the final .spine, JSON and atlas assets so a model can drive a full art pipeline without hand-authoring rig data.49-
- AlicenseAqualityCmaintenanceEnables an AI assistant to create, edit, validate and animate Esoteric Software Spine 2D skeletons without the editor running, covering bones, slots, attachments, skins, events, constraints, keyframes and reference-safe renames or deletions. When the Spine editor is installed, it also drives the official CLI to import skeleton JSON into a project and export runtime JSON/binary with atlases.262MIT