Blender MCP with Gemini AI Agent

Note: A fork of BlenderMCP by Siddharth Ahuja, enhanced with Google’s ADK for autonomous multi-step task execution.

Control Blender 3D using natural language with Google Gemini AI, powered by MCP and Google ADK.

---

🎯 Features

• Multi-step task planning: Breaks down complex requests into smaller operations.
• Tool chaining: Calls multiple tools to accomplish goals.
• Scene reasoning: Queries scene info before making changes.
• Blender Python execution: Translates natural language into executable commands.

Example:

You: "Create a metallic red sphere above a blue cube with studio lighting"
Agent:
  1. Creates cube (blue material)
  2. Creates sphere (metallic red, positioned above)
  3. Adds studio lighting
  4. Returns: "Scene created with metallic red sphere, blue cube, and studio lighting"

---

🏗️ Architecture

┌─────────────┐ → ┌──────────────────┐ → ┌──────────────┐ → ┌─────────────┐
│   Gemini    │   │   MCP Server     │   │  Google ADK  │   │   Blender   │
│   Client    │   │   (FastMCP)      │   │    Agent     │   │   (Addon)   │
└─────────────┘   └──────────────────┘   └──────────────┘   └─────────────┘

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• Blender 3.0+
• Google Gemini API Key (Get one)
• uv package manager (Installation guide)

Installation

1. Clone the repo:

   git clone https://github.com/PocoLibre/blender-mcp.git
   cd blender-mcp

2. Run the installer:
   • Windows: ./install.bat
   • Linux/macOS: chmod +x install.sh run_server.sh run_client.sh && ./install.sh
3. Set up .env:

   GEMINI_API_KEY="your-api-key"

4. Install the Blender addon:
   • Open Blender → Edit → Preferences → Add-ons → Install addon.py → Enable "Gemini Connector for Blender".

Usage

1. Start the MCP Server:

   ./run_server.bat  # Windows
   ./run_server.sh   # Linux/Mac

2. Start Blender with the addon enabled.
3. Run the Gemini Client:

   ./run_client.bat  # Windows
   ./run_client.sh   # Linux/Mac

4. Enter commands:

   Enter your command for Blender (or 'quit' to exit): create a metallic sphere
   

---

🛠️ Agent Tools

• get_blender_scene_info: Get scene details (objects, materials, lighting).
• execute_blender_python_code: Execute Python code in Blender.
• web_search: Search for assets/tutorials.
• download_asset: Download files to assets/downloads/.

---

⚙️ Configuration

.env File

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash  # Free tier: 15 req/min
VERBOSE=false                  # Set to 'true' for detailed logging
BLENDER_HOST=localhost         # Blender addon host
BLENDER_PORT=9876             # Blender addon port

---

📁 Project Structure

blender-mcp/
├── src/
│   └── blender_mcp/
│       └── server.py         # MCP server with Google ADK Agent
├── addon.py                  # Blender addon (socket server)
├── gemini_client.py          # Gemini client (calls MCP server)
├── install.bat/sh            # Installation scripts
├── run_server.bat/sh         # Server launcher
├── run_client.bat/sh         # Client launcher
├── pyproject.toml            # Python dependencies
└── README.md

---

💡 Example Commands

Simple:

• "Create a cube at the origin"
• "Make a red sphere"
• "What version of Blender am I running?"

Complex:

• "Create a metallic red sphere above a blue cube"
• "Add a camera pointing at the scene with studio lighting"

---

⚠️ Security & Rate Limits

• Security: Only use on trusted local networks. Review generated code before execution.
• Rate Limits: Free tier allows 15 requests/minute for gemini-2.5-flash.

---

🙏 Credits

• Original Project: Siddharth Ahuja
• This Fork: Enhanced with Google ADK Agent for autonomous task execution.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Made with ❤️ for the AI and Blender community

License: MIT Built With: Google ADK, FastMCP, Google Gemini AI, Blender Python API