Skip to main content
Glama
Spine Pipeline MCP

Spine Pipeline MCP

by RainLib

Spine2d-mcp: a local bridge between Spine and coding agents

Spine2d-mcp

English | 简体中文 | 日本語 | 한국어

License: MIT

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-spine

The equivalent Claude Code commands are:

claude plugin marketplace add RainLib/Spine2d-mcp
claude plugin install spine-pipeline@rainlib-spine

Both 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 --global

Replace 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-mcp

The 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

spine-asset-prep

Prepare these AI assets for Spine; use a connected PhotoCraft/Photoshop MCP for layers and previews when available.

spine-rig-animation

Adjust this rig's mesh and weights, then validate the requested animation and secondary motion.

spine-game-integration

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

skeleton_inspect

Read source JSON version, bones, animations and SHA-256

skeleton_validate

Static source bone/reference/mesh/weight/timeline checks

stage_json_copy

Byte-for-byte JSON-only copy to a new job

stage_asset_bundle

Isolated JSON + referenced images; rebases image paths

job_validate

Static validation of an existing staged skeleton

mesh_inspect

Source/job mesh inventory, edge connectivity, boundary/fan defects and influence statistics

mesh_weights_get

Paged named influences and bone-local bind coordinates from a staged mesh

mesh_weights_set

Replace selected vertices' existing weights, normalize and sort in a new job

mesh_replace

Replace explicit geometry in a new job, retaining the attachment's texture metadata

mesh_policy_validate

Caller-defined continuity/budget/rigidity/direct-weight/ancestor-isolation rules

animation_copy

Copy an animation under a new name in a new job

animation_retime

Scale times by 1/speed in a new job; linear/stepped only

bone_keys_set

Set rotate/translate/scale keys in a new job; Spine 4.3 rotate uses value

spine_export

Explicitly configured licensed CLI imports a copied JSON and exports project/JSON/atlas/PNG

godot_validate

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-mcp

The 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-godot

The 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 E

There 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 D

core.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 build

Unit 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 tools
animation_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_validateB
Read-only

Run static structural checks against a staged job, without changing it.

Inputs: job_id (required).

mesh_inspectA
Read-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_validateC
Read-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_getB
Read-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_inspectA
Read-only

Inspect a Spine JSON in the configured read-only root; basic checks, not full validation.

Inputs: relative_path (required).

skeleton_validateB
Read-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

    B3.2/5.0

    Scored across 15 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      9
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      26
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      This 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.
      38
      16 npm
      MIT