3D MCP
Overview
3D-MCP is a universal implementation of the Model Context Protocol for 3D software. It creates a unified TypeScript interface for LLMs to interact with Blender, Maya, Unreal Engine, and other 3D applications through a single coherent API.
// LLMs use the same interface regardless of underlying 3D software
await tools.animation.createKeyframe({
objectId: "cube_1",
property: "rotation.x",
time: 30,
value: Math.PI/2
});
Core Philosophy & Design Decisions
3D-MCP is built on four interconnected architectural principles that together create a unified system for 3D content creation:
Entity-First Design: Well-defined domain entities form the foundation of all operations, enabling consistent data modeling across platforms
Type-Safe CRUD Operations: Automated generation of create, read, update, delete operations with complete type validation
Atomic Operation Layer: A minimal set of platform-specific implementations that handle fundamental operations
Composable Tool Architecture: Complex functionality built by combining atomic operations in a platform-agnostic way
This architecture creates a dependency inversion where platform-specific implementation details are isolated to atomic operations, while the majority of the codebase remains platform-independent.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ LLM / User API โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Tool API
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Compound Operations โ
โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Modeling Tools โ โ Animation Tools โ โ Rigging Tools โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Implemented by
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Atomic Operations โ
โ โ
โ โโโโโโโโโโโโ Entity CRUD โโโโโโโโโโโโโ โโโโโโโโโโโ Non-CRUD โโโโโโโโโโ โ
โ โ create{Entity}s update{Entity}s ...โ โ select, undo, redo, etc. โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Plug-in Server Request
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Platform-Specific Adapters โ
โ โ
โ โโโโโ Blender โโโโโ โโโโโโโ Maya โโโโโโ โโโโ Unreal Engine โโโโโ โ
โ โ createKeyframes โ โ createKeyframes โ โ createKeyframes โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Why These Design Decisions?
Entity-First Design was chosen because:
3D applications use different object models but share core concepts (meshes, materials, animations)
Zod schemas provide single-source-of-truth for validation, typing, and documentation
Strong typing catches errors at compile time rather than runtime
Rich metadata enables better AI understanding of domain objects
CRUD Operations as Foundation because:
They map cleanly to what 3D applications need to do with entities
Standardized patterns reduce cognitive overhead
Auto-generation eliminates repetitive code using createCrudOperations
Every entity automatically gets the same consistent interface
Atomic and Compound Tool Separation because:
Only atomic tools need platform-specific implementation (~20% of codebase)
Compound tools work across all platforms without modification (~80% of codebase)
New platforms only need to implement atomic operations to gain all functionality
Maintainable architecture with clear separation of concerns
Technical Architecture
1. Entity-Centric CRUD Architecture
The system's foundation is a rich type system of domain entities that generates CRUD operations:
// Define entities with rich metadata using Zod
export const Mesh = NodeBase.extend({
vertices: z.array(Tensor.VEC3).describe("Array of vertex positions [x, y, z]"),
normals: z.array(Tensor.VEC3).optional().describe("Array of normal vectors"),
// ... other properties
});
// CRUD operations generated automatically from entity schemas
const entityCruds = createCrudOperations(ModelEntities);
// => Creates createMeshs, getMeshs, updateMeshs, deleteMeshs, listMeshs
// All operations preserve complete type information
await tool.createRigControls.execute({
name: "arm_ctrl",
shape: "cube", // TypeScript error if not a valid enum value
targetJointIds: ["joint1"], // Must be string array
color: [0.2, 0.4, 1], // Must match Color schema format
// IDE autocomplete shows all required/optional fields
});
Entity schemas provide:
Schema Validation: Runtime parameter checking with detailed error messages
Type Information: Complete TypeScript types for IDE assistance
Documentation: Self-documenting API with descriptions
Code Generation: Templates for platform-specific implementations
Entity Architecture Diagram
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Core Entity Definitions โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ BaseEntity โ โ NodeBase โ โ Other Core Entities โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โฒ
โ extends
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Domain-Specific Entities โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Model โ โ Animation โ โ Rigging โ โ
โ โ Entities โ โ Entities โ โ Entities โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ input to
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Automatic CRUD Generation โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ createCrudOperations(Entities) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ generates
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Atomic Operations โ
โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ
โ โ create{Entity}s โ โ get{Entity}s โ โ update{Entity}s โ .. โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ foundation for
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Compound Operations โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ No need for platform-specific code. Use atomic ops only.โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
2. Compound Tool Architecture
The system creates a clear separation between atomic and compound operations:
// From compounded.ts - Higher level operations composed from atomic operations
createIKFKSwitch: defineCompoundTool({
// ...parameter and return definitions...
execute: async (params) => {
// Create IK chain using atomic operations
const ikChainResult = await tool.createIKChains.execute({/*...*/});
// Create control with full type-checking
const ikControlResult = await tool.createRigControls.execute({
name: `${switchName}_IK_CTRL`,
shape: ikControlShape, // Type-checked against schema
targetJointIds: [jointIds[jointIds.length - 1]],
color: ikColor,
// ...other parameters
});
// Position the control at the end effector
await tool.batchTransform.execute({/*...*/});
// Create constraints to connect the system
await tool.createConstraint.execute({/*...*/});
// Return standardized response with created IDs
return {
success: true,
switchControlId: switchControlResult.id,
ikControlId: ikControlResult.id,
fkControlIds,
poleVectorId: poleVectorId || undefined,
};
}
})
This architecture provides several technical advantages:
Atomic Operations (~20% of the system):
Directly interact with platform APIs
Need platform-specific implementations
Focus on single entity operations (create, read, update, delete)
Form minimal implementation required for new platforms
Compound Operations (~80% of the system):
Built entirely from atomic operations
Zero platform-specific code
Implement higher-level domain concepts
Work on any platform without modification
Tool Composition Flow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ High-Level Tool Definition โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Compound Tool Pattern โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ defineCompoundTool({ โ โ
โ โ description: string, โ โ
โ โ parameters: zod.Schema, โ โ
โ โ returns: zod.Schema, โ โ
โ โ execute: async (params) => { โ โ
โ โ // Composed entirely from atomic operations โ โ
โ โ await tool.atomicOperation1.execute({...}); โ โ
โ โ await tool.atomicOperation2.execute({...}); โ โ
โ โ return { success: true, ...results }; โ โ
โ โ } โ โ
โ โ }) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Plug-in Server Request
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Platform Adaptation โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Blender Implementation โ โ Maya Implementation โ โ
โ โ of Atomic Operations โ โ of Atomic Operations โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Key files for the compound tool architecture:
compounded.ts: Compound modeling tools
compounded.ts: Compound animation tools
compounded.ts: Compound rigging tools
3. Code Generation Pipeline
The system automatically generates platform-specific implementations from TypeScript definitions:
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Entity Schemas โ โ Schema โ โ Platform-Specific Code โ
โ & Tools (TS) โ โโ> โ Extraction (TS) โ โโ> โ (Python/C++/etc.) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โ
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Type โ โ Parameter โ โ Implementation โ
โ Definitions โ โ Validation โ โ Templates โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
Key aspects of the generation system:
Entity Extraction: Analyzes Zod schemas to understand entity structure
Parameter Mapping: Converts TypeScript types to platform-native types
Validation Generation: Creates parameter validation in target languages
Implementation Templates: Provides platform-specific code patterns
The codegen system is implemented in:
4. Domain Organization
The system is organized into domains that mirror 3D content creation workflows:
Core: Base entities and operations used across all domains
Modeling: Mesh creation, editing, and topology operations
Animation: Keyframes, curves, clips, and animation control
Rigging: Skeletal systems, controls, and deformation
Rendering: Materials, lights, and render settings
Each domain follows the same organizational pattern:
entity.ts: Domain-specific entity definitions
atomic.ts: Atomic operations for domain entities
compounded.ts: Higher-level operations built from atomic tools
Domain Structure Diagram
packages/src/tool/
โ
โโโ core/ # Core shared components
โ โโโ entity.ts # Base entities all domains use
โ โโโ utils.ts # Shared utilities including CRUD generation
โ โโโ ...
โ
โโโ model/ # Modeling domain
โ โโโ entity.ts # Mesh, Vertex, Face, etc.
โ โโโ atomic.ts # Atomic modeling operations
โ โโโ compounded.ts # Higher-level modeling tools
โ โโโ ...
โ
โโโ animation/ # Animation domain
โ โโโ entity.ts # Keyframe, AnimCurve, Clip, etc.
โ โโโ atomic.ts # Atomic animation operations
โ โโโ compounded.ts # Higher-level animation tools
โ โโโ ...
โ
โโโ rig/ # Rigging domain
โ โโโ entity.ts # Joint, IKChain, Control, etc.
โ โโโ atomic.ts # Atomic rigging operations
โ โโโ compounded.ts # Higher-level rigging tools
โ โโโ ...
โ
โโโ rendering/ # Rendering domain
โโโ entity.ts # Camera, Light, RenderSettings, etc.
โโโ atomic.ts # Atomic rendering operations
โโโ compounded.ts # Higher-level rendering tools
โโโ ...
5. Entity-Centric CRUD Architecture
The system implements a sophisticated entity-centric approach where:
Entities as Domain Models: Each domain (modeling, animation, rigging) defines its core entities that represent its fundamental concepts. These are implemented as Zod schemas with rich type information.
CRUD as Foundation: Every entity automatically receives a complete set of CRUD operations (Create, Read, Update, Delete) through the createCrudOperations utility:
// Each domain starts with CRUD operations for all its entities
const entityCruds = createCrudOperations(ModelEntities);
const modelAtomicTools = {
...entityCruds, // Foundation of all atomic tools
// Domain-specific operations build on this foundation
}
Entity Reuse and Inheritance: Core entities defined in core/entity.ts are extended by domain-specific entities, promoting code reuse and consistent design across domains.
DDD-Inspired Architecture: The system follows Domain-Driven Design principles by organizing code around domain entities and aggregates rather than technical concerns.
This architecture provides several key benefits:
Consistency: All entities have the same patterns for basic operations
Reduced Boilerplate: CRUD operations are generated automatically
Clear Organization: Tools are organized around domain entities
Separation of Concerns: Each domain manages its own entities while sharing common patterns
The combination of rich entity models with automatic CRUD operations creates a robust foundation that simplifies development while maintaining flexibility for domain-specific operations.
Getting Started
# Install dependencies
bun install
# Run the server
bun run index.ts
# Extract schemas and generate plugins
bun run packages/scripts/plugin-codegen.ts
Development Workflow
Define Entities: Create or extend entity schemas in src/tool/<domain>/entity.ts
Generate CRUD: Use createCrudOperations to generate atomic operations
Create Compound Tools: Build higher-level operations from atomic tools
Generate Plugins: Run the code generator to create platform-specific implementations
Contributing
The architectural decisions in 3D-MCP make it uniquely extensible:
Add New Entities: Define new entities and automatically get CRUD operations
Add New Compound Tools: Combine existing atomic operations to create new functionality
Add New Platforms: Implement the atomic tool interfaces in a new plugin
See our contributing guide for more details on how to contribute.
3D-MCP: One API to rule all 3D software