Threlte MCP


An MCP (Model Context Protocol) server that enables AI agents to inspect and manipulate Three.js/Threlte scenes in real-time.

✅ Compatible With

- Claude Desktop - Anthropic's desktop app
- Antigravity - Google's AI IDE
- Claude Code - CLI tool for Claude
- Cursor - AI-powered code editor
- Windsurf - Codeium's AI IDE
- Continue - VS Code AI extension
- Any MCP-compatible client

See detailed compatibility guide →

Features

- 🔍 Scene Inspection - View the full 3D scene hierarchy, find objects by name/type
- 🎯 Object Manipulation - Move, rotate, scale, show/hide objects
- 🎨 Materials & Assets - Apply materials, load GLTF models, change environment
- 🧪 Asset Analysis - Inspect GLTF structure and validate performance
- dYZ+ Asset Optimization - Simplify meshes, compress textures, prune unused data
- dY"? Svelte Export - Generate Threlte/Svelte components from GLTF
- dYZ? Camera Presets - Save, load, and animate camera views
- ⚡ Physics Control - Add physics bodies, apply impulses, set gravity
- 🎭 Vibe Presets - Apply mood presets (cozy, spooky, neon, etc.)

Installation

``bash
npm install threlte-mcp
`

Quick Start

$3

`bash
npm install threlte-mcp
`

$3

`bash
npx threlte-mcp setup
`

This auto-detects your IDE (Antigravity, Cursor, Claude Desktop) and creates the MCP config.

$3

Requires Svelte 5 for the MCPBridge component.

`svelte




`

That's it! The AI can now inspect and manipulate your scene.

---



📋 Manual Configuration (Alternative)

If npx threlte-mcp setup doesn't work for your IDE, manually add to your config:

`json
{
"mcpServers": {
"threlte-mcp": {
"command": "npx",
"args": ["-y", "threlte-mcp"]
}
}
}
`

Config file locations:
- Antigravity: ~/.gemini/antigravity/mcp_config.json
- Cursor: ~/.cursor/mcp.json
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)







🔧 Advanced: TypeScript API

`typescript
import { MCPBridge } from 'threlte-mcp/client';
import { useThrelte } from '@threlte/core';

const { scene } = useThrelte();

// Create bridge (auto-connects in dev mode)
const bridge = new MCPBridge(scene, {
url: 'ws://127.0.0.1:8082', // default
autoConnect: true, // default in dev
reconnectDelay: 60000, // 1 minute
});

// In render loop
bridge.update();

// Get scene state
bridge.getSceneState();

// Find objects
bridge.findObjects({ nameContains: 'player' });
`






Option B: Per-Scene (Simple for prototyping)

`svelte

`

$3

Once both the MCP server and your Threlte app are running, AI agents can:

`
"Get the scene state"
"Find all objects named 'Player'"
"Move the 'Camera' to position [0, 5, 10]"
"Apply the 'neon' vibe to the scene"
`

Available Tools

$3

| Tool | Description |
|------|-------------|
| get_scene_state | Get full scene hierarchy |
| find_objects | Search by name, type, or userData |
| get_object_position | Get position of specific object |
| log_positions | Export positions for code |

$3

| Tool | Description |
|------|-------------|
| set_camera_position | Set camera position, lookAt, and lens settings |
| save_camera_preset | Save current camera view as a preset |
| load_camera_preset | Load a saved camera view |
| list_camera_presets | List all saved camera presets |
| delete_camera_preset | Delete a saved camera preset |
| animate_camera_presets | Animate through a sequence of presets |

$3

| Tool | Description |
|------|-------------|
| spawn_entity | Create primitive (box, sphere, etc.) |
| destroy_entity | Remove object from scene |
| move_object | Set object position |
| set_transform | Set position, rotation, scale |
| set_visibility | Show/hide object |
| rename_entity | Rename object |
| duplicate_entity | Clone object |

$3

| Tool | Description |
|------|-------------|
| make_physical | Add physics body |
| remove_physics | Remove physics body |
| apply_impulse | Apply force |
| set_gravity | Set global gravity |

$3

| Tool | Description |
|------|-------------|
| analyze_gltf | Inspect GLTF/GLB structure |
| validate_asset | Validate GLTF/GLB for issues |
| optimize_gltf | Optimize GLTF/GLB assets |
| export_to_svelte | Generate Threlte/Svelte component |

$3

| Tool | Description |
|------|-------------|
| load_asset | Load GLTF/GLB model |
| apply_material | Set material |
| set_environment | Set skybox/environment |

$3

| Tool | Description |
|------|-------------|
| apply_vibe | Apply mood preset |
| get_bridge_status | Check connection status |

Configuration

$3

The server uses port 8082 by default for WebSocket communication.

$3

The MCPBridge auto-connects in development mode. For production, you can enable it via environment variable:

`bash

Add to .env file:

VITE_MCP_ENABLED=true
`

This is useful for:
- Testing in production builds
- Demo environments
- Debugging production issues

Note: Auto-enabled in development mode (npm run dev), no configuration needed.

Development

`bash

Clone the repo

git clone https://github.com/RaulContreras123/threlte-mcp.git
cd threlte-mcp

Install dependencies

npm install

Run in development

npm run dev

Build for production

npm run build
``

License

MIT © Raul Contreras