Spline 3D Design MCP server

The Spline.design Integration Server provides robust integration with Spline.design 3D scenes through multiple operational modes: MCP Server for Claude Desktop integration, Webhook Server for data-driven visualizations, and a lightweight Minimal Server with essential functionality.

Installation Options

Local Installation

# 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

Running 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 configuration options through its 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

Using with Claude Desktop

To use the server with Claude Desktop in MCP mode:

1. Start the server 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. Begin interacting with Spline.design through Claude

Using Webhook Mode

The webhook server enables real-time data-driven visualizations:

1. Start the webhook server:

   node bin/cli.js --mode webhook
   

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

3. Create a webhook and obtain its URL

4. Configure the webhook in Spline.design's Variables & Data Panel

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

Key Features

3D Object Management

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

Material System

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

Event & Action System

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

Runtime API Integration

• Direct integration with @splinetool/runtime
• Generate JavaScript, React, and Next.js code
• Create interactive animations and behaviors
• Implement custom event handling

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "spline-design" '{"command":"node","args":["bin/cli.js","--mode","mcp","--transport","stdio"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "spline-design": {
            "command": "node",
            "args": [
                "bin/cli.js",
                "--mode",
                "mcp",
                "--transport",
                "stdio"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "spline-design": {
            "command": "node",
            "args": [
                "bin/cli.js",
                "--mode",
                "mcp",
                "--transport",
                "stdio"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect