Spine Pipeline MCP
Provides local, staging-first tools for Spine asset pipelines, including inspecting and validating Spine JSON skeletons, staging JSON/image bundles, copying and retiming animations, setting bone keys, exporting via a licensed Spine CLI, and validating with a Spine-enabled Godot project.
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., "@Spine Pipeline MCP inspect minimal.json, validate it, and stage a copy in a new job"
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.

Spine2d-mcp
A local, staging-first MCP foundation for Spine asset pipelines.
The repository/display name is Spine2d-mcp; the Python package and executable remain spine-pipeline-mcp for existing client compatibility. The project icon is unchanged. The banner uses the official, unmodified Spine mark only to identify compatibility; Codex and Claude Code are plain-text labels, not official logos or endorsements. See third-party notices.
Install / marketplaces · Connect Codex / Claude · Authoring skills · Architecture · Security · Contributing
Early prototype, project version 0.2.1. This repository uses the official Python MCP SDK 2.3.0. That SDK version is not a claim of “MCP protocol 2.0”, FastMCP 2.x, or project version 2.0. The fifteen tools below are implemented. Output remains staging-only; there is no publication tool.
Install MCP + Skills
The MCP executes tools; the Skills guide the agent's workflow. Use both for asset preparation → Spine rigging/animation → runtime integration. All paths and game-specific conventions come from the user.
All three Skills use English for instructions, references, and interface metadata. The repository plugin is version 0.2.2; the MCP server and published Registry bundle are version 0.2.1.
Discovery and downloads: three Skills on skills.sh · official MCP Registry entry · version 0.2.1 MCPB release. In the Registry search, enter io.github.RainLib/spine-pipeline-mcp. The repository plugins below combine all fifteen MCP tools and the three skills.
Option A: install the combined plugin
With a recent Codex CLI supporting codex plugin, register the repository marketplace and install its plugin:
codex plugin marketplace add RainLib/Spine2d-mcp
codex plugin add spine-pipeline@rainlib-spineThe equivalent Claude Code commands are:
claude plugin marketplace add RainLib/Spine2d-mcp
claude plugin install spine-pipeline@rainlib-spineBoth bundle the MCP and all three skills. Install Git, uv and Python 3.11+, then complete the one-time directory setup: Codex forwards the two SPINE_MCP_*_ROOT environment variables; Claude prompts for source and staging directories. Installing the plugin alone does not select your assets. JSON operations need no Spine license; native export requires your own installed, licensed Spine.
Option B: install Skills and MCP separately
For clients without plugin support, use the skills.sh CLI (Node.js 22.20+) to install the three skills for Codex:
npx skills add RainLib/Spine2d-mcp \
--skill spine-asset-prep spine-rig-animation spine-game-integration \
--agent codex --globalReplace codex with claude-code, or list both. Omit --global for a project installation. Skills installation does not register an MCP server. Add the MCP to Codex without manually cloning or creating a Python environment:
uvx --from git+https://github.com/RainLib/Spine2d-mcp.git@main python -c 'import spine_pipeline_mcp'
codex mcp add spine-pipeline \
--env SPINE_MCP_SOURCE_ROOT=/absolute/path/to/test-assets \
--env SPINE_MCP_STAGING_ROOT=/absolute/path/to/separate-staging \
-- uvx --from git+https://github.com/RainLib/Spine2d-mcp.git@main spine-pipeline-mcpThe first command downloads/builds the server before the client's startup timeout applies. Replace both paths; source must exist and neither directory may contain the other. uvx installs from Git, so this command does not depend on a PyPI release. For repeatable setups, replace main with v0.2.1 or a full commit. See Claude's equivalent command, timeout setup, updates and registry details. Choose one installation route per client to avoid duplicate tools and skills.
Option C: install the Registry MCPB bundle
The official Registry name is io.github.RainLib/spine-pipeline-mcp. Its package points to the MCPB download, with a SHA-256 checksum in server.json. Import this file in a client supporting MCPB 0.4 and the UV runtime, then supply the source and staging directories when prompted. This bundle targets macOS/Linux and installs Python dependencies on first launch; it contains the MCP server. Install Skills separately with Option B.
The Registry provides discovery metadata; installation support depends on the client. Codex/Claude Code users can use Option A or B. See the bundle requirements and verification steps.
Use it
Start a new client session and first ask it to call skeleton_inspect on a JSON file relative to your configured source root. Then invoke a skill:
Skill | Example request |
Prepare these AI assets for Spine; use a connected PhotoCraft/Photoshop MCP for layers and previews when available. | |
Adjust this rig's mesh and weights, then validate the requested animation and secondary motion. | |
Integrate the character into the target I specify, including slots, attachments, skins and events. |
In Codex, use $spine-rig-animation for a standalone skill or $spine-pipeline:spine-rig-animation for the plugin. In Claude, use /spine-rig-animation or /spine-pipeline:spine-rig-animation, respectively. Photo editors are optional integrations discovered at use time. Skills do not add missing editor APIs; see capabilities and local extensions.
Related MCP server: Companion Animation Pipeline MCP Server
What works today
Tool | Behavior |
| Read source JSON version, bones, animations and SHA-256 |
| Static source bone/reference/mesh/weight/timeline checks |
| Byte-for-byte JSON-only copy to a new job |
| Isolated JSON + referenced images; rebases image paths |
| Static validation of an existing staged skeleton |
| Source/job mesh inventory, edge connectivity, boundary/fan defects and influence statistics |
| Paged named influences and bone-local bind coordinates from a staged mesh |
| Replace selected vertices' existing weights, normalize and sort in a new job |
| Replace explicit geometry in a new job, retaining the attachment's texture metadata |
| Caller-defined continuity/budget/rigidity/direct-weight/ancestor-isolation rules |
| Copy an animation under a new name in a new job |
| Scale times by 1/speed in a new job; linear/stepped only |
| Set rotate/translate/scale keys in a new job; Spine 4.3 rotate uses |
| Explicitly configured licensed CLI imports a copied JSON and exports project/JSON/atlas/PNG |
| Explicitly configured native Spine-enabled Godot loads and briefly samples animations in an isolated minimal project |
All transformations create a new job, preserving their input job and the original source. Animation copying refuses existing target names. Setting keys replaces only the selected timeline in the new copy. Retiming/setting keys rejects numeric Bezier curves rather than silently distorting them.
Static validation checks bone references/cycles, slot references, mesh UV/triangles, packed weighted vertices, bone indices, weight sums and timeline times. Multiple meshes are reported, not automatically rejected: attachment count alone cannot prove that the body mesh is continuous or that a rig follows an art policy.
Mesh edits currently require Spine 4.3.x and reject documents containing linked meshes, image sequences or deform/FFD/attachment animation timelines. Weight edits retain existing bone-local bind coordinates; changing weights can change the pose. Explicit mesh replacement supports locally generated geometry and new bindings with supplied coordinates. See mesh operations and local extensions for schemas, limits and the ProjectAdapter Python API.
Verified scope
Local copy-only smoke testing exercised the real MCP stdio tools: stage a weighted-mesh rig, copy/retime/edit an animation, export with Spine 4.3.26, then import/load/initialize/briefly sample using a Spine-enabled Godot 4.7.1 custom build. This is one locally tested combination, not a cross-version compatibility guarantee. Local test assets and paths are not distributed.
Not implemented
Spine editor GUI control or live timeline/weight-paint editing
Automatic alpha-contour meshing, rig creation, interactive weight painting or constraint authoring
GIF/rendered preview, full-timeline deformation/foot-drift/face-rigidity quality checks
Publishing back into a game, automatic retention/quota, remote HTTP hosting
Audio assets, image sequences or complete linked-mesh semantics
No Spine executable, game-specific engine binary, commercial assets, proprietary project files or game scripts are included. The example fixture is synthetic schema-shaped test data, not a production rendering rig.
Local development quick start
Requirements: Git, Python 3.11+, uv, and an MCP client supporting stdio. You do not need Spine installed to use the current JSON-only tools.
git clone https://github.com/RainLib/Spine2d-mcp.git
cd Spine2d-mcp
uv sync --locked
uv run --locked pytest -q
SPINE_MCP_SOURCE_ROOT="$PWD/examples/source" \
SPINE_MCP_STAGING_ROOT="$PWD/.staging" \
uv run --locked spine-pipeline-mcpThe last command starts a stdio MCP server waiting for a client; it is not an interactive CLI. Stop it with Ctrl-C. Start with the synthetic sample or your own test copies, not a production asset root.
Codex configuration (TOML)
Codex uses a named TOML table, not a mcpServers JSON object. Review the Codex template and merge it into the intended config without replacing existing settings:
[mcp_servers.spine-pipeline]
command = "uv"
args = ["--directory", "/path/to/Spine2d-mcp", "run", "--locked", "spine-pipeline-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300
[mcp_servers.spine-pipeline.env]
SPINE_MCP_SOURCE_ROOT = "/path/to/test-assets"
SPINE_MCP_STAGING_ROOT = "/path/to/separate-staging"A separate CODEX_HOME (for example an API-account wrapper) does not inherit this entry automatically. An actual read-only Codex MCP tool invocation has been verified, not merely config parsing.
Claude Code configuration (JSON)
Claude Code uses mcpServers JSON. This format is not Codex TOML. Adapt the following or use the Claude Code template. Replace every placeholder with an actual absolute path. If the client cannot find uv, use its absolute executable path.
{
"mcpServers": {
"spine-pipeline": {
"type": "stdio",
"timeout": 300000,
"command": "uv",
"args": ["--directory", "/path/to/Spine2d-mcp", "run", "--locked", "spine-pipeline-mcp"],
"env": {
"SPINE_MCP_SOURCE_ROOT": "/path/to/Spine2d-mcp/examples/source",
"SPINE_MCP_STAGING_ROOT": "/path/to/Spine2d-mcp/.staging"
}
}
}
}For a session-only Claude connection, use claude --mcp-config /path/to/private-spine.mcp.json --strict-mcp-config. Claude Code's isolated health check has been verified as Connected; a Claude model-driven call has not been claimed. The client guide explains scopes, verification and the licensed Spine CLI chain.
Example calls for source-reading tools:
{"relative_path": "minimal.json"}Both root variables are required. Source must already exist. Source and staging must be separate and neither may contain the other. Tools fail closed if the configuration is absent or invalid. Source paths must be relative to the configured source root.
Optional native tools
The JSON tools need no installed editor. To enable CLI export, explicitly configure:
export SPINE_MCP_CLI=/path/to/Spine
export SPINE_MCP_CLI_VERSION=4.3.26
export SPINE_MCP_GODOT_EXECUTABLE=/path/to/spine-enabled-godotThe skeleton's version must exactly match the configured CLI version. Spine must already be installed/licensed; the server does not acquire a license. Stock Godot does not necessarily contain the native SpineSprite class; godot_validate reports failure when it is absent. Run native tools only on assets you trust.
Example sequence:
stage_asset_bundle(relative_path="rig.json") -> job A
animation_copy(job_id=A, source="idle", target="idle_preview") -> job B
animation_retime(job_id=B, animation="idle_preview", speed=1.2) -> job C
job_validate(job_id=C) -> static report
spine_export(job_id=C) -> export job D
godot_validate(job_id=D) -> independent validation job EThere is no automatic last step publishing D into a game. Inspect the outputs and reports before deciding how to use them.
Architecture
MCP client → stdio server
├─ inspect / validate → source JSON (read only)
└─ stage bundle → immutable job A (JSON + images)
└─ animation transforms → new job B
└─ pinned Spine CLI → new export job C
└─ isolated Godot project → new check job Dcore.py handles source boundaries; validation.py, animation.py, mesh.py and mesh_policy.py provide JSON operations; pipeline.py handles staging and fixed CLI calls; godot_check.py builds a minimal standalone verification project. adapter.py composes explicit local transforms/validators with staging. Per-game paths and art policies belong in a local adapter outside this repository. See architecture.
Why Python rather than Go? Python can reuse image processing, NumPy/Pillow mesh work, JSON transforms and validation scripts in existing art pipelines. Go has attractive binary distribution, but requiring a Python worker for those operations would add another boundary before it adds value.
Safety model
Explicit source root, JSON-only reads, 16 MiB per JSON.
Reject requested absolute paths, parent traversal, symlinks and non-regular files.
Bundled images must resolve below the configured source; max 256 images / 128 MiB.
New UUID jobs; no overwrite/delete/publish tools or arbitrary shell text.
Native executable paths are administrator configuration, not tool-call arguments; commands use fixed argument arrays and timeouts.
Godot runs a generated minimal project with no game autoloads and isolated HOME/XDG.
Spine outputs are isolated, but the licensed editor can access its normal license/cache/settings. This is not an OS sandbox.
Log sizes are checked after each native command; they are not a hard live disk quota.
Use trusted directories/assets/executables. A hostile local process concurrently changing files/mounts is outside the threat model. Asset metadata and tool output are untrusted data, not instructions. Staging has no automatic retention/quota policy. See SECURITY.md.
Testing and CI
uv sync --locked
uv run --locked pytest -q
uv buildUnit tests use synthetic copies and mocked native executables. The stdio integration test invokes a real MCP subprocess. Licensed Spine/Godot tests are local, opt-in manual checks, not public CI fixtures.
An inactive CI template is provided for Linux Python 3.11/3.12 and a package build. Hosted CI is not enabled or verified yet: the publishing credential lacks workflow-write scope. A maintainer with appropriate access can place the template at .github/workflows/ci.yml and inspect the run.
License and third-party software
Project code and synthetic examples: MIT. Third-party trademarks and the official Spine mark are excluded from that license; see THIRD_PARTY_NOTICES.md. Dependencies retain their own licenses. Spine is commercial software by Esoteric Software and is not bundled or licensed by this project. Future CLI integrations require a separately installed, appropriately licensed copy and compliance with the applicable Spine terms. This is an independent community project, not an official Spine integration.
References
Available Tools
15 toolsanimation_copyA
Copy an existing animation to a new name in a NEW staging job; refuses name collisions.
Inputs: job_id (required), source (required), target (required).
animation_retimeA
Return a new job with animation times divided by positive speed. Only linear/stepped; rejects Bezier.
Inputs: speed (required), job_id (required), animation (required).
bone_keys_setC
Replace one rotate/translate/scale timeline in a NEW job. Spine 4.3 rotate uses value. Linear/stepped only.
Inputs: bone (required), keys (required), job_id (required), timeline (required), +1 more.
godot_validateC
Use configured native Spine-enabled Godot in an isolated project. Runtime load/sample, not visual approval.
Inputs: job_id (required).
job_validateBRead-only
Run static structural checks against a staged job, without changing it.
Inputs: job_id (required).
mesh_inspectARead-only
Inventory skins/meshes, topology, continuity and weights. Supply exactly one source path or job ID. Static only.
Inputs: job_id, relative_path.
mesh_policy_validateCRead-only
Check {rules:[{skin,slot,attachment,continuous?,max_vertices?,max_influences?,regions?}]}. Regions use vertices plus allowed_bones/rigid_bone/forbidden_ancestors. Static only.
Inputs: job_id (required), policy (required).
mesh_replaceB
NEW job: replace uvs/triangles/vertices/hull (optional edges), preserving texture. Continuous geometry only; Spine 4.3; no deform/linked meshes. Weighted vertices need explicit bind coordinates.
Inputs: skin (required), slot (required), job_id (required), geometry (required), +1 more.
mesh_weights_getBRead-only
Read up to 256 vertices with named bones, bone-local bind coordinates and weights from a staged mesh.
Inputs: skin (required), slot (required), job_id (required), attachment (required), +2 more.
mesh_weights_setC
NEW job: updates=[{vertex:0,weights:{bone:1}}]. Replace existing bindings' weights, normalize/sort; retain bind x/y. Spine 4.3 only; no deform/linked meshes. Does not preserve pose.
Inputs: skin (required), slot (required), job_id (required), updates (required), +1 more.
skeleton_inspectARead-only
Inspect a Spine JSON in the configured read-only root; basic checks, not full validation.
Inputs: relative_path (required).
skeleton_validateBRead-only
Statically check bone references, mesh topology/weights and timeline times. Not a visual guarantee.
Inputs: relative_path (required).
spine_exportC
Run explicitly configured licensed Spine CLI on another copy; produce project/JSON/atlas/PNG. Staging only.
Inputs: job_id (required).
stage_asset_bundleB
Create an isolated JSON + referenced image bundle. No source writes. No audio/sequences.
Inputs: relative_path (required).
stage_json_copyA
Copy one Spine JSON into a new isolated staging job. Never changes the source.
Inputs: relative_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
The set contains four validation-flavored tools (job_validate, skeleton_validate, mesh_policy_validate, godot_validate) and two inspection tools (mesh_inspect, skeleton_inspect) whose boundaries are only partially clarified by the descriptions. mesh_inspect vs skeleton_inspect vs skeleton_validate overlap substantially (both inventory meshes/weights and topology), and an agent may pick the wrong one. The descriptions do differentiate them somewhat (static vs runtime, policy vs structural), keeping it above the low band.
Most tools follow a clear resource_action pattern (job_validate, mesh_inspect, skeleton_validate, animation_copy, bone_keys_set, spine_export, godot_validate). The two stage_* tools (stage_json_copy, stage_asset_bundle) invert to verb_noun, a minor deviation. Overall predictable and readable.
15 tools sits at the top of the well-scoped band and covers a genuinely multi-stage pipeline (stage, inspect, validate, edit, export, runtime-check). A couple of the validation/ inspection tools could plausibly be merged, but none feel like pure filler. The count is defensible for the domain's breadth.
The core lifecycle is covered: stage source, inspect, validate, mutate weights/mesh/animations/bone keys, export, and runtime-verify in Godot. Gaps are moderate rather than fatal: there is no job listing/status or staging-job delete/cleanup, and no tool to create slots/attachments or inspect atlases/textures. Agents can work around these but lifecycle cleanup is a dead end.
Maintenance
Related MCP Connectors
Render Spine 3.8 skeleton animations to PNG frames or GIF. Pay per call with points.
Drive a live Cinevva game session: edit game files, import CC0 assets, preview changes.
Create 2D characters and animations, revise sprites, adjust timing and export assets via OAuth.
OAuth account tools, image/video generation (Pro), Studio handoffs. No local vault access.
Related MCP Servers
- FlicenseAqualityBmaintenanceEnables converting layered PSD or PhotoshopToSpine exports into validated Spine 2D rigs, animations, atlases, previews, runtime JSON, and optionally editable .spine projects. It provides MCP tools and an OpenAI/Codex workflow for rigging, animation generation, validation, preview auditing, and batch processing.14-
- AlicenseBqualityBmaintenanceEnables AI clients to control background Blender jobs over stdio so they can inspect a 3D character or companion model, calibrate its anatomy and named bones, bake and export animation, and numerically verify the persisted GLB for playback review. Includes a CLI, models and workspaces that stay local unless explicitly shared.9MIT
- 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.261MIT
- AlicenseBqualityBmaintenanceThis server enables AI agents to read, measure, view, and safely edit Spine 4.3 animations by bridging the gap between creative artistic decisions and technical requirements. It facilitates a comprehensive animation pipeline, ensuring all changes are verified, backed up, and ready for deployment across various rendering environments.3816 npmMIT