What is Spline Mcp Server

The spline-mcp-server is an MCP server designed to work with the Spline 3D design tool API, providing a user-friendly interface for interacting with Spline’s features.

Use cases

Use cases include exporting 3D scenes for web applications, importing models for interactive experiences, creating animations for user interactions, and managing complex projects within the Spline environment.

How to use

To use the spline-mcp-server, install it via npm with ‘npm install spline-mcp-server’ or run it directly using ‘npx spline-mcp-server’. Configure your API credentials in a ‘.env’ file, and use various commands to export scenes, import models, and create animations.

Key features

Key features include exporting Spline scenes to multiple formats (GLB, GLTF, FBX, OBJ), importing 3D models, managing animations (creating, triggering, and listing), and retrieving scene details.

Where to use

The spline-mcp-server can be used in fields such as game development, interactive media, virtual reality, and any application requiring 3D design and animation.

Spline.design Integration Server

This server provides comprehensive integration with Spline.design 3D scenes through multiple modes:

1. MCP Server - Full Model Context Protocol integration for Claude Desktop
2. Webhook Server - Standalone webhook support for data-driven visualizations
3. Minimal Server - Lightweight option with essential functionality

Features

• Comprehensive 3D Object Management

  • Create, modify, and delete any 3D object
  • Control positioning, rotation, scaling, and visibility
  • Generate runtime code for object interactions

• Runtime API Integration

  • Direct integration with @splinetool/runtime for programmatic control
  • Generate ready-to-use JavaScript, React, and Next.js code
  • Create interactive animations and behaviors
  • Implement custom event handling and scene manipulation

• Advanced Material System

  • Create layered materials with extensive customization
  • Support for all Spline material types and properties
  • Configure complex shading options

• Complete Event & Action System

  • Support for 20+ event types (mouse, keyboard, physics, etc.)
  • Implementation of 15+ action types
  • Create complex event chains and conditional logic

• Webhook Integration

  • Create webhooks to receive external data
  • Build real-time data visualizations
  • Connect with services like Zapier, IFTTT, n8n, or custom APIs

Installation

Option 1: Install and run locally

# Clone the repository
git clone https://github.com/yourusername/spline-mcp-server.git
cd spline-mcp-server

# Install dependencies
npm install

# Configure environment variables
cp config/.env.example .env

# Start the server in MCP mode (for Claude Desktop)
npm start

Option 2: Run different server modes

# Start in MCP mode (default)
node bin/cli.js --mode mcp

# Start in webhook mode
node bin/cli.js --mode webhook

# Start in minimal mode
node bin/cli.js --mode minimal

Command-Line Options

The server supports various command-line options through the unified CLI:

# Get help
node bin/cli.js --help

# MCP mode with HTTP transport
node bin/cli.js --mode mcp --transport http --port 3000

# MCP mode with stdio transport (for Claude Desktop)
node bin/cli.js --mode mcp --transport stdio

# Webhook server mode
node bin/cli.js --mode webhook --port 3000

Project Structure

spline-mcp-server/
├── bin/                   # Executable scripts
│   └── cli.js             # Unified CLI entry point
├── config/                # Configuration files
│   ├── .env.example       # Environment variables template
│   └── *.json             # JSON configuration files
├── docs/                  # Documentation
│   ├── INSTALLATION.md    # Installation guide
│   ├── USAGE_GUIDE.md     # Usage instructions
│   └── WEBHOOK_GUIDE.md   # Webhook specific guide
├── examples/              # Example usage patterns
├── package-templates/     # Package.json templates for different modes
├── public/                # Web assets
│   └── webhook-ui.html    # Webhook UI interface
├── scripts/               # Shell scripts
│   ├── install.sh         # Installation script
│   └── test-*.sh          # Testing scripts
├── src/                   # Source code
│   ├── prompts/           # Prompt templates
│   ├── resources/         # MCP resources
│   ├── tools/             # MCP tools
│   ├── utils/             # Utility functions
│   └── index.js           # Main MCP entry point
├── minimal.js             # Minimal server implementation
├── simple-webhook-server.js # Standalone webhook server
├── LICENSE                # License file
├── README.md              # Project readme
└── package.json           # Unified package file

Using with Claude Desktop

This server is designed to work with Claude Desktop in MCP mode:

1. Start the server in MCP mode with stdio transport:

   node bin/cli.js --mode mcp --transport stdio
   

2. In Claude Desktop, access the MCP connection settings

3. Connect to the server

4. Start interacting with Spline.design through Claude

Using Webhook Mode

The webhook server provides a simple web interface for creating and testing webhooks:

1. Start the server in webhook mode:

   node bin/cli.js --mode webhook
   

2. Open the web interface at http://localhost:3000

3. Create a webhook and obtain its URL

4. In Spline.design, configure the webhook in the Variables & Data Panel

5. Send test data to see your scene update in real-time

Examples

See the examples/ directory for sample usage patterns and common workflows.

Documentation

For detailed documentation, see the files in the docs/ directory:

• Installation Guide
• Usage Guide
• Webhook Guide
• Testing Guide

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.