Blender MCP Server
Model Context Protocol (MCP) server for complete Blender control via API
This addon transforms Blender into an MCP server, exposing 50+ powerful tools that can be orchestrated by AI agents through HTTP endpoints. Perfect for AI-driven 3D workflows, automation, and creative experimentation.
✨ Features
-
🚀 50+ Tools - Complete control over Blender's features:
- Object creation, manipulation, and transformation
- Material and shader system management
- Animation and keyframe control
- Camera and lighting setup
- Modifiers and constraints
- Physics simulations (rigid body, cloth, fluid)
- Geometry nodes and procedural generation
- File import/export operations
- Scene optimization and batch operations
-
🔒 Thread-Safe Execution - Enterprise-grade queue system for safe concurrent operations
-
📦 Auto-Install Dependencies - Automatically installs required packages on first run
-
🎮 Simple UI Panel - Start/stop server with one click from Blender's N-panel
-
📊 Real-time Monitoring - Track operations, statistics, and server status
-
🔧 Production-Ready - Comprehensive error handling, logging, and caching
🚀 Quick Start
Installation
- Download
blender_mcp.py - Open Blender
- Go to Edit → Preferences → Add-ons
- Click the dropdown arrow (⌄) next to the search bar
- Select Install from Disk...
- Choose the downloaded
blender_mcp.pyfile - Enable the addon by checking the box next to "MCP Complete Server for Blender"
Starting the Server
- Press N in the 3D Viewport to open the sidebar
- Navigate to the MCP Server tab
- Click Start Server
- Server will start on
http://localhost:8000
The addon will automatically install required dependencies on first run (FastAPI, Uvicorn, Pydantic, etc.).
🤖 Using with PolyMCP
This MCP server is designed to work seamlessly with PolyMCP - a powerful framework for orchestrating MCP servers with AI agents.
Example: AI-Controlled Blender
#!/usr/bin/env python3
import asyncio
from polymcp.polyagent import UnifiedPolyAgent, OllamaProvider
async def main():
# Initialize your LLM provider
llm = OllamaProvider(model="gpt-oss:120b-cloud", temperature=0.1)
# Connect to Blender MCP server
agent = UnifiedPolyAgent(
llm_provider=llm,
mcp_servers=["http://localhost:8000/mcp"],
verbose=True
)
async with agent:
print("✅ Blender MCP Server connected!\n")
# Chat with your AI to control Blender
while True:
user_input = input("\n🎨 You: ")
if user_input.lower() in ['exit', 'quit']:
break
result = await agent.run_async(user_input, max_steps=5)
print(f"\n🤖 Blender: {result}")
if __name__ == "__main__":
asyncio.run(main())
Example Commands
Once connected, you can ask the AI agent to:
- "Create a cube at position (0, 0, 0) with size 2"
- "Add a red metallic material to the selected object"
- "Create a camera looking at the origin"
- "Set up a simple lighting scene with 3 lights"
- "Add a fluid simulation to the cube"
- "Export the scene as an FBX file"
- "Create an animation rotating the object 360 degrees over 100 frames"
That's it! PolyMCP handles all the complexity of:
- Tool discovery and selection
- Multi-step task planning
- Error handling and retries
- State management across operations
This makes it incredibly simple to build AI-powered Blender automation tools!
📡 API Endpoints
Once the server is running, you can access:
- API Documentation:
http://localhost:8000/docs - List All Tools:
http://localhost:8000/mcp/list_tools - Invoke Tool:
POST http://localhost:8000/mcp/invoke/{tool_name}
🛠️ Available Tool Categories
View all tool categories (100+ tools)
- Object Operations: Create, delete, duplicate, select objects
- Transformations: Move, rotate, scale, apply transforms
- Materials & Shading: Create materials, add textures, setup shader nodes
- Modeling: Add modifiers, boolean operations, mesh editing
- Animation: Keyframes, timeline control, NLA editor
- Camera & Lighting: Camera setup, light creation, HDRI environments
- Rendering: Render settings, output configuration, rendering
- Physics: Rigid body, cloth, fluid simulations
- Geometry Nodes: Procedural generation, node tree creation
- File Operations: Import/export various formats (FBX, OBJ, USD, etc.)
- Scene Management: Scene info, cleanup, optimization
- Batch Operations: Multi-object creation and transformation
- Advanced: Particle systems, force fields, grease pencil
🔧 Configuration
You can customize the server by editing the Config class in blender_mcp.py:
class Config:
HOST = "0.0.0.0" # Server host
PORT = 8000 # Server port
AUTO_INSTALL_PACKAGES = True # Auto-install dependencies
THREAD_SAFE_OPERATIONS = True # Enable thread-safe execution
ENABLE_CACHING = True # Enable result caching
📋 Requirements
The addon automatically installs these dependencies:
- FastAPI
- Uvicorn
- Pydantic
- docstring-parser
- NumPy
- PolyMCP
Blender Version: 3.0.0 or higher
🐛 Troubleshooting
Server won't start?
- Check Blender's System Console for error messages (Window → Toggle System Console)
- Ensure port 8000 is not already in use
- Try restarting Blender after installation
Dependencies not installing?
- Manually install packages using Blender's Python:
/path/to/blender/python -m pip install fastapi uvicorn pydantic docstring-parser numpy
Can't find MCP Server panel?
- Press N in the 3D Viewport
- Look for "MCP Server" tab in the sidebar
- Make sure the addon is enabled in Preferences
🤝 Contributing
Contributions are welcome! This project demonstrates how simple it is to create powerful MCP servers for PolyMCP.
📝 License
MIT License - See LICENSE file for details
🔗 Related Projects
- PolyMCP - Simple and efficient way to interact with MCP servers using custom agents
- Model Context Protocol - Open protocol for tool integration with LLMs
💡 Why This Project?
This MCP server was created to demonstrate how incredibly simple PolyMCP makes it to build AI-powered tools. With just a few lines of code, you can:
- Expose complex Blender functionality as MCP tools
- Let AI agents discover and orchestrate these tools
- Build natural language interfaces for 3D creation
No complex prompting, no manual tool selection, no state management - PolyMCP handles it all!
Designed for PolyMCP
Star ⭐ this repo if you find it useful!