spline

Spline.design Integration Server exposes multiple modes to connect Spline.design scenes to external control flows. In MCP mode, the server offers a full Model Context Protocol integration intended for Claude Desktop users to programmatically manage 3D objects, scenes, materials, and events. The webhook mode provides a standalone interface to receive external data in real time and drive visualizations, while the minimal server offers a lightweight option for essential functionality. The server also integrates with @splinetool/runtime, allowing you to generate runtime code snippets in JavaScript, React, and Next.js, enabling interactive scenes and custom event handling.

To get started, run the MCP server in MCP mode to enable Claude Desktop integration, or switch to webhook or minimal mode depending on your use case. Use the CLI to switch modes, supply transport options, and set the port if needed. The server comes with a comprehensive command-line interface that supports help, mode selection, and transport configuration. When connected, you can programmatically create, modify, and delete 3D objects, set positions, rotations, scales, and visibility, and define event-action chains to drive complex behaviors inside your Spline scene. The runtime integration makes it straightforward to generate code that you can drop into web apps, enabling live scene manipulation and interactive animations.

Prerequisites:

• Node.js (14.x or newer) and npm installed on your machine
• Git (optional, for cloning the repo)

Installation steps:

1. Clone the repository (or download the release):

git clone https://github.com/yourorganization/spline-mcp-server.git
cd spline-mcp-server

2. Install dependencies:

npm install

3. Configure environment variables:

cp config/.env.example .env

Edit .env to suit your environment (API keys, endpoints, ports, etc.). 4) Run the server in MCP mode (default Claude Desktop integration):

npm start

5. (Optional) Run specific server modes via CLI:

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

# Webhook mode
node bin/cli.js --mode webhook

# Minimal mode
node bin/cli.js --mode minimal

If you cloned from a repo that uses a monorepo or different startup script, follow the repository’s specific guidance in docs/INSTALLATION.md.

Note: The project may include a config directory with environment templates (config/.env.example) that you should tailor to your deployment needs.

Tips and common issues:

• Make sure Node.js version matches the project’s minimum requirement (check package.json engines or docs).
• If you encounter transport issues in MCP mode, try switching to stdio transport for Claude Desktop compatibility or use http transport with explicit port configurations.
• Ensure your environment variables (API keys, endpoints) are correctly set in .env before starting the server.
• Webhook mode requires the webhook UI to be accessible; verify that the port (default 3000) is open in your environment.
• When generating runtime code, choose the target framework (JavaScript, React, Next.js) that best fits your project to minimize integration work.
• Review the docs/ directory for detailed usage instructions, including installation, usage, and webhook guides.