spline-mcp

MCP server for Spline.design code generation and asset management.

Overview

Spline.design is a 3D design tool that exports interactive scenes for the web. This MCP server provides:

• Code Generation: Generate React, Next.js, and vanilla JS integration code
• Asset Management: Download, cache, and validate .splinecode files
• Integration Support: WebSocket (Mahavishnu) and n8n workflow integration
• Helper Utilities: URL building, event documentation, code snippets

Note: Spline does not have a traditional REST API. Scenes are created in the Spline editor and exported as .splinecode files for runtime use.

Installation

uv pip install -e .

Quick Start

Generate a React Component

spline-mcp generate react https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode

Download a Scene

spline-mcp download https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode

MCP Server Usage

Stdio Mode (default)

spline-mcp serve

HTTP Mode

spline-mcp serve --http --port 3048

Available Tools

Code Generation

Asset Management

Helper Utilities

Integration

Configuration

Set via environment variables with SPLINE_ prefix:

Generated Code Examples

React Component

import { Suspense, useRef, useCallback } from 'react';
import Spline from '@splinetool/react-spline';

interface HeroSceneProps {
  className?: string;
}

export function HeroScene({ className }: HeroSceneProps) {
  return (
    <Suspense fallback={<div>Loading 3D scene...</div>}>
      <Spline
        scene="https://prod.spline.design/xxx/scene.splinecode"
        className={className}
      />
    </Suspense>
  );
}

With WebSocket Integration

// Auto-generated WebSocket integration with soft failover
const { subscribe, isConnected } = useWebSocket('ws://localhost:8690');

useEffect(() => {
  if (!isConnected) return;

  const unsubscribe = subscribe('spline:variables', (data) => {
    splineRef.current?.setVariables(data);
  });

  return unsubscribe;
}, [isConnected]);

Architecture

spline_mcp/
├── generators/         # Code generation (React, Vanilla, Next.js)
│   ├── base.py         # Base classes and types
│   ├── react.py        # React generator with FastBlocks patterns
│   ├── vanilla.py      # Vanilla JS/HTML generator
│   └── nextjs.py       # Next.js SSR generator
├── assets/             # Asset management
│   ├── manager.py      # Download, cache, validate
│   └── validator.py    # Scene file validation
├── integrations/       # External integrations
│   ├── websocket.py    # Mahavishnu WebSocket (soft failover)
│   └── n8n.py          # n8n workflow integration
├── tools/              # MCP tool definitions
│   ├── generation.py   # Code generation tools
│   ├── assets.py       # Asset management tools
│   ├── helpers.py      # Utility tools
│   └── integration.py  # Integration tools
├── config.py           # Oneiric-based configuration
└── server.py           # FastMCP application

Ecosystem Integration

Part of the Bodai Ecosystem:

License

BSD-3-Clause