# Spine MCP > Local MCP server for Spine CLI automation, JSON animation generation, and corpus-guided animation presets. - **Type:** MCP server - **Install:** `agentstack add mcp-1425sd-spine-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [1425sd](https://agentstack.voostack.com/s/1425sd) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [1425sd](https://github.com/1425sd) - **Source:** https://github.com/1425sd/spine-MCP ## Install ```sh agentstack add mcp-1425sd-spine-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # spine-mcp English | [简体中文](README.zh-CN.md) 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: ```text Spine -i "" -o "" -e "" ``` 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: ```powershell & "$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 ```powershell 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. ```powershell $env:SPINE_EXE = "C:\Program Files\Spine\Spine.com" ``` Example for a custom local install path: ```powershell $env:SPINE_EXE = "E:\BaiduNetdiskDownload\Spine pro 3.8.75+K'D\Spine.com" ``` Confirm the CLI is reachable and note the version: ```powershell & "$env:SPINE_EXE" --help ``` To persist it for future PowerShell sessions: ```powershell [Environment]::SetEnvironmentVariable("SPINE_EXE", "C:\Program Files\Spine\Spine.com", "User") ``` If `SPINE_EXE` is not set, the server runs `Spine` directly. ## Build ```powershell npm.cmd run build npm.cmd run typecheck ``` ## Start ```powershell 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: ```powershell claude mcp add --transport stdio spine-mcp -- node G:\spine-mcp\build\index.js ``` With an explicit Spine CLI path: ```powershell 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: ```text Spine -i "" ``` 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: ```text 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: ```text Spine -i "G:\cat\cat.json" -o "G:\cat\cat.spine" -r ``` Optional: - `skeletonName` is added after `-r` - `scale` is added with `-s ` 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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 ` 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`. ```text 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 ```text 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 ```text 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: ```text Spine -i "" -o "G:\spine-mcp\.cache\corpus-json\" -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 ```text 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 ```text 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 ```powershell 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. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [1425sd](https://github.com/1425sd) - **Source:** [1425sd/spine-MCP](https://github.com/1425sd/spine-MCP) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-1425sd-spine-mcp - Seller: https://agentstack.voostack.com/s/1425sd - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.