🦴 Spine MCP Server

AI-driven Spine 3.8.75 animation workflow server — lets AI clients (Trae / Cursor / Claude Desktop) directly control Spine.

📖 Overview

Spine MCP Server is a server built on the MCP (Model Context Protocol) that wraps Spine 3.8.75 Professional editor capabilities into 70 MCP tools, allowing AI clients to directly:

• Read Spine projects (bones, slots, skins, animations, events, constraints)

• Modify animation keyframes (rotation, translation, scale, shear, curves)

• Edit skeleton structure (add/delete bones, slots, attachments, skins, outfit swapping)

• Manipulate constraints (IK, transform, path) and meshes (FFD deformation)

• Split atlases (extract parts from character illustrations), auto-rig, repack atlases

• Render animation preview frames via JS runtime

• One-click configuration, start/stop service, and generate AI client configs via Cocos Creator extension panel

Related MCP server: unreal-animation-mcp

✨ Features

🔧 Requirements

• Node.js ≥ 20 (tested on v22)

• Spine.com (3.8.75 Professional, e.g. D:\cocos\SpinePro3.8.75\Spine.com)

• Optional: Cocos Creator 3.8+ (for extension panel)

🚀 Quick Start

# 1. Install dependencies + build
npm install
npm run build

# 2. Configure Spine path (or run the installer wizard)
npm run installer        # Auto-detect Spine/Cocos/Node and write .env

# 3. Verify
node dist/index.js check
node dist/index.js info "D:/cocos/SpinePro3.8.75/examples/hero/hero-pro.spine"

🤖 MCP Config

Add the following configuration to your Trae / Cursor / Claude Desktop MCP server settings:

{
  "mcpServers": {
    "spine-mcp": {
      "command": "node",
      "args": ["D:/cocos/spine-mcp-server/dist/index.js", "mcp"],
      "env": { "SPINE_EXE": "D:/cocos/SpinePro3.8.75/Spine.com" }
    }
  }
}

⚠️ If MCP shows "No tools yet", restart your AI client to allow the server process to reload.

🧩 Tools (70)

🎮 Cocos Extension

The cocos-extension/ directory provides a Cocos Creator 3.8+ panel:

• Installation: Extension Manager → Local Extension → Add cocos-extension directory (or run npm run package:ccx to generate a .ccx file for import)

• Features: Start/stop MCP service, scan projects, generate AI config, service status

• See docs/cocos-extension-README.en.md for details

🧪 Tests

npm run test:all     # Run all test suites (unit + integration + MCP protocol + extension bridge)
npm run test:unit    # Unit tests only (node:test)

Test matrix: Unit 20/20 · Phase 3 37/37 · Phase 4 45/45 · Phase 5 13/13 · MCP Protocol 10/10 (70 tools) · Extension Bridge 12/12

📚 Docs

• User Manual (EN)

• User Manual (中文)

• Cocos Extension README (EN)

• Cocos Extension README (中文)

🗂 Project Structure

├── src/                  # Source code (TypeScript)
│   ├── server.ts         # MCP stdio server
│   ├── spine/            # Core: cli-executor / json-handler / export / import / render / split ...
│   ├── tools/            # 70 tools (registered in registry.ts)
│   └── utils/            # Config / logger / error codes / file utilities
├── cocos-extension/      # Cocos Creator extension (panel)
├── scripts/              # Installer wizard / .ccx packaging
├── tests/                # All test suites
└── docs/                 # Specs, manuals, progress

💰 Support

Available on the Swarms Marketplace

📄 License

MIT