spine-mcp

English | 简体中文

GitHub shows this English README.md by default. The Chinese version is maintained in README.zh-CN.md.

Local MCP server for Spine automation on Windows. It only calls the official Spine CLI and communicates over stdio, so AI tools like Claude Code, Codex, and Cursor can start it locally.

This server does not do UI automation, AutoHotkey, mouse or keyboard simulation, timeline operations, mesh binding, bone weight editing, or direct .spine internals modification. It only modifies .spine files through the official Spine CLI.

Requirements

• Windows
• Node.js 20+
• Spine installed locally. This MCP does not include Spine and cannot run without a local Spine installation.
• A Spine CLI executable available as either:
  • SPINE_EXE, preferably pointing to Spine.com
  • or a Spine command available on PATH

Spine Version Compatibility

This MCP package is version 0.1.0.

The Spine CLI command construction in this project has been checked against local Spine Pro / Spine Launcher 3.8.75. In particular, Spine 3.8.75 requires export commands to use an export settings JSON file:

Spine -i "<project.spine>" -o "<outputDir>" -e "<export-settings.json>"

If a command fails even though the input paths are correct, first check whether your local Spine version has different CLI flags or export behavior. Run:

& "$env:SPINE_EXE" --help

Then compare the output with the command shown by the MCP result. Different Spine versions may require different export settings JSON formats, support different flags, or reject commands that work in 3.8.75.

Install

cd G:\spine-mcp
npm.cmd install

Configure Spine

Recommended: point SPINE_EXE to your local Spine.com. The example below is the default install style, but use the actual path for your own Spine installation.

$env:SPINE_EXE = "C:\Program Files\Spine\Spine.com"

Example for a custom local install path:

$env:SPINE_EXE = "E:\BaiduNetdiskDownload\Spine pro 3.8.75+K'D\Spine.com"

Confirm the CLI is reachable and note the version:

& "$env:SPINE_EXE" --help

To persist it for future PowerShell sessions:

[Environment]::SetEnvironmentVariable("SPINE_EXE", "C:\Program Files\Spine\Spine.com", "User")

If SPINE_EXE is not set, the server runs Spine directly.

Build

npm.cmd run build
npm.cmd run typecheck

Start

node G:\spine-mcp\build\index.js

The server uses stdio. Do not expect normal terminal output on stdout because stdout is reserved for the MCP protocol. Diagnostic logs go to stderr.

Add To Claude Code

Basic setup:

claude mcp add --transport stdio spine-mcp -- node G:\spine-mcp\build\index.js

With an explicit Spine CLI path:

claude mcp add --transport stdio --env SPINE_EXE="C:\Program Files\Spine\Spine.com" spine-mcp -- node G:\spine-mcp\build\index.js

Tools

spine_info

Inspect a .spine, .json, .skel, or folder input:

Spine -i "<inputPath>"

Use this when you need Spine CLI metadata. Do not use it to export, pack, import, clean, open, or modify files.

spine_export

Export a Spine project:

Spine -i "G:\cat\cat.spine" -o "G:\cat\dist" -e export-settings.json

Optional flags:

• -m when clean=true

The exportSettingsPath parameter is required and must be a path to an existing Spine export settings JSON file. exportModeOrSettings is kept only as a deprecated compatibility alias. Mode strings like json or json+pack are not accepted by the Spine CLI -e flag.

Use this for official CLI exports. Do not use it for texture-only packing, JSON import, UI automation, or internal project edits.

spine_import_json

Import JSON, binary skeleton data, or another supported input into a .spine project:

Spine -i "G:\cat\cat.json" -o "G:\cat\cat.spine" -r

Optional:

• skeletonName is added after -r
• scale is added with -s <scale> before -o

Use this for official CLI imports. Do not use it for packing textures or direct project internals editing.

spine_clean

Run animation clean up:

Spine -i "G:\cat\cat.spine" -m

Use this for Spine CLI clean up only. It does not delete user files.

spine_open_project

Open a .spine project in the local Spine application without waiting for Spine to exit:

Spine "G:\cat\cat.spine"

Use this when you want to continue manual editing. Do not use it for exports or UI automation.

Animation Workflow

This server works with existing .spine projects and Spine JSON files. All animation generation is applied to a copy of the source files, leaving the originals untouched.

Recommended workflow

1. Have an existing .spine project or Spine JSON file ready.
2. Use spine_analyze_json to inspect the skeleton structure.
3. Use spine_control_bones, spine_build_animation_from_json, or spine_build_animation_from_existing_project to add animations.
4. Use spine_export to export the final output.

spine_analyze_json

Read-only inspection of a Spine JSON file:

Use spine_analyze_json:
jsonPath = G:\cat\cat.json

Returns skeleton metadata, bones, slots, skins, attachments, animations, and inferred roles.

spine_add_simple_animation

Low-level debug tool when you know the exact bone:

Use spine_add_simple_animation:
sourceJsonPath = G:\psd-spine\cat.json
outputJsonPath = G:\cat-output\cat.tail-test.json
animationName = tail_test
targetBone = tail
animationType = rotate
keyframes = [
  { "time": 0, "angle": -10 },
  { "time": 0.5, "angle": 10 },
  { "time": 1, "angle": -10 }
]
overwrite = true

It supports only rotate, translate, and scale timelines on one bone.

spine_control_bones

Control multiple existing bones by writing custom rotate, translate, and scale timelines into a Spine JSON copy:

Use spine_control_bones:
sourceJsonPath = G:\cat\cat.json
outputJsonPath = G:\cat-output\cat.controlled.json
animationName = custom_pose_loop
boneControls = [
  {
    "boneName": "head",
    "rotate": [
      { "time": 0, "angle": -4 },
      { "time": 0.5, "angle": 4 },
      { "time": 1, "angle": -4 }
    ],
    "translate": [
      { "time": 0, "y": 0 },
      { "time": 0.5, "y": 6 },
      { "time": 1, "y": 0 }
    ]
  },
  {
    "boneName": "tail",
    "rotate": [
      { "time": 0, "angle": -12 },
      { "time": 0.5, "angle": 12 },
      { "time": 1, "angle": -12 }
    ]
  }
]
overwrite = true

This is the main tool for explicit bone control. It validates that each bone exists and writes JSON animation data only. It does not drag bones in the Spine editor, bind meshes, edit weights, create IK, or directly mutate .spine binaries.

spine_generate_animation_json

Generate an animated JSON copy only:

Use spine_generate_animation_json:
sourceJsonPath = G:\cat\cat.json
outputJsonPath = G:\cat-output\cat.animated.json
userGoal = "cute cat loading animation with breathing, head float, tail swing, and blink"
animationName = generated_loop
duration = 2
characterType = cat
overwrite = true

Supported basic animation kinds include:

• breathing: body/root scale
• head_float: head translate
• tail_swing: tail rotate
• blink: eye slot attachment switch, or eye bone scale fallback
• paw_wave: paw/hand/arm rotate
• logo_bounce: root/logo translate and scale
• floating: root/body translate

spine_create_loading_animation_preset

Focused loading presets:

Use spine_create_loading_animation_preset:
sourceJsonPath = G:\cat\cat.json
outputJsonPath = G:\cat-output\cat.loading.json
preset = cute_cat_loading
duration = 2
intensity = normal
overwrite = true

Supported presets:

• cute_cat_loading
• logo_bounce
• breathing_idle
• floating_character
• blink_loop

Use soft intensity for subtle UI loading loops and strong only when you want visibly larger motion.

spine_build_animation_from_json

One-step JSON pipeline:

Use spine_build_animation_from_json:
sourceJsonPath = G:\cat\cat.json
imagesDir = G:\cat\images
outputDir = G:\cat-output
projectName = cute_cat_loading
userGoal = "Make a cute cat loading animation. Body breathes, head floats, tail swings, eyes blink."
animationName = loading_loop
characterType = cat
exportSettingsPath = G:\cat\export-settings.json
openAfterBuild = true
overwrite = true
knowledgeDir = G:\spine-mcp\knowledge

It runs:

analyze JSON -> generate animated JSON -> import .spine -> pack textures -> export -> optionally open project

If exportSettingsPath is omitted, the tool still imports the generated .spine project and can open it, but it skips the final export step because Spine 3.8.75 requires -e <settings.json> for exports.

spine_build_animation_from_existing_project

Build animations on an existing .spine project or Spine JSON. Keeps original files untouched and writes a modified copy to outputDir.

Use spine_build_animation_from_existing_project:
spineProjectPath = G:\cat-source\cat.spine
outputDir = G:\cat-output
projectName = cute_cat_existing
userGoal = "Add a restrained idle animation with breathing and blinking."
characterType = cat
exportSettingsPath = G:\cat\export-settings.json
openAfterBuild = true
overwrite = true

When spineProjectPath is used without sourceJsonPath, provide sourceExportSettingsPath for the temporary project-to-JSON export. If it is omitted, the tool falls back to exportSettingsPath/exportMode when present.

This workflow only creates basic region/slot/keyframe animation. It does not bind mesh, edit weights, create IK, or modify the original .spine binary.

Corpus Learning Layer

If you have many local Spine source projects, run corpus learning first. This is not large-model training. It is local statistical analysis that extracts patterns from real .spine and .json projects, then writes markdown and JSON knowledge files that AI tools and MCP tools can read later.

Your source files are not uploaded. The server only reads the corpus directory, exports .spine files to local .cache/corpus-json/ when needed, and writes knowledge files to knowledge/ or the directory you choose.

Step 1: Scan Corpus

Use spine_scan_corpus:
corpusDir = G:\spine-corpus
maxProjects = 20

This only confirms how many .spine and .json files can be found. It does not parse projects or call Spine CLI.

Step 2: Learn Corpus

Use spine_learn_from_corpus:
corpusDir = G:\spine-corpus
outputKnowledgeDir = G:\spine-mcp\knowledge
exportSettingsPath = G:\spine-corpus\json-export-settings.json
maxProjects = 819
overwrite = true

For .json files, MCP parses them directly. For .spine files, MCP calls Spine CLI export:

Spine -i "<project.spine>" -o "G:\spine-mcp\.cache\corpus-json\<project>" -e "G:\spine-corpus\json-export-settings.json"

If exportSettingsPath is omitted, .json corpus files can still be analyzed directly, but .spine corpus files cannot be exported and are recorded as failed projects.

If a project fails to export or parse, it is recorded in failedProjects and the batch continues.

Step 3: Read Guide

Use spine_get_generation_guide:
knowledgeDir = G:\spine-mcp\knowledge

This returns the markdown guide plus machine-readable presets and naming rules. If the files do not exist, it asks you to run spine_learn_from_corpus.

Step 4: Recommend Parameters

Use spine_recommend_animation_params:
userGoal = "Make a cute cat loading animation with breathing, head bob, tail swing, and blinking."
characterType = cat
availableAssetRoles = ["body", "head", "tail", "eye_left", "eye_right"]
knowledgeDir = G:\spine-mcp\knowledge

This returns recommended animations, duration, learned preset params, warnings, and a short reasoning summary. If knowledge is missing, it falls back to built-in defaults.

Development

npm.cmd run dev

For production MCP usage, build first and run build/index.js.

Result Format

CLI-backed tools return JSON text containing:

• command
• args
• stdout
• stderr
• exitCode
• success

This makes Spine CLI errors visible to the calling AI tool without crashing the MCP server.