spline-mcp-server

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.