Chat with Blender

<div align="center"> <img src="assets/logo.png" alt="Chat with Blender Logo" width="200"> <h1>Chat with Blender</h1> <h3>Blender MCP Server</h3> </div>

<p align="center"> <img src="https://img.shields.io/badge/Blender-3.0%2B-orange?logo=blender" alt="Blender 3.0+"> <img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python" alt="Python 3.10+"> <img src="https://img.shields.io/badge/MCP-Compatible-green" alt="MCP Compatible"> <img src="https://img.shields.io/badge/License-MIT-yellow" alt="MIT License"> <img src="https://img.shields.io/badge/Vibe-Coded-ff69b4" alt="Vibe Coded"> </p>

<p align="center"> <strong>🎨 Control Blender with AI</strong><br> Create, edit, and render 3D models through chat </p>

<p align="center"> <a href="#-features">Features</a> • <a href="#-installation">Installation</a> • <a href="#-usage">Usage</a> • <a href="#%EF%B8%8F-mcp-tools">MCP Tools</a> • <a href="#-security">Security</a> </p>

---

⚡ Vibe Coding Project: This project was developed with AI assistant help using the "vibe coding" approach. It may contain experimental features and unexpected bugs. Your contributions and bug reports are highly appreciated!

---

🎬 Demo

<p align="center"> <img src="screenshots/scene-example.png" alt="Chat with Blender Demo" width="800"> </p>

<p align="center"> <em>AI-generated terrarium scene - trees, clouds, and glass box</em> </p>

---

✨ Features

Chat with Blender enables AI assistants to directly control Blender using the Model Context Protocol (MCP).

Feature	Description
🎯 Object Creation	Cube, sphere, cylinder, torus, text, and more
🔧 Object Editing	Modify position, rotation, scale
🎭 Material Control	Color, metallic, roughness, emission settings
💡 Lighting	Point, Sun, Spot, Area lights
📷 Camera	Camera creation and setup
🖼️ Render	Convert scene to image
🐍 Code Execution	Execute custom Python code

Supported Platforms

<table> <tr> <td align="center"><img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Claude_AI_logo.svg" width="60"><br><strong>Claude Desktop</strong></td> <td align="center"><img src="https://lmstudio.ai/favicon.ico" width="60"><br><strong>LM Studio</strong></td> <td align="center"><img src="https://cursor.sh/favicon.ico" width="60"><br><strong>Cursor</strong></td> </tr> </table>

---

⚠️ Important Warnings

🧪 Experimental Project

This project is in active development. You may encounter:

• 🐛 Unexpected bugs and crashes
• 🔄 API changes
• 📦 Missing features
• 🎨 Material/color issues (check viewport mode!)

Our recommendation: Save and backup your important Blender projects!

---

🚀 Installation

Requirements

• Blender 3.0 or higher (5.0+ tested)
• Python 3.10 or higher
• Claude Desktop or LM Studio (MCP supported)

Step 1: Download the Project

git clone https://github.com/Akerdogmus/chat-with-blender.git
cd chat-with-blender

Step 2: Install Python Dependencies

pip install mcp httpx

Step 3: Install the Blender Addon

1. Open Blender
2. Go to Edit → Preferences → Add-ons menu
3. Click the "Install..." button in the top right
4. Select the downloaded addon.py file
5. Check the "Interface: Blender MCP" checkbox

<p align="center"> <img src="screenshots/chat-with-blender-kurulum.png" alt="Blender Addon Installation" width="600"> </p>

Step 4: MCP Client Configuration

For Claude Desktop

1. Open the config file:

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

2. Add the following configuration:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["C:/path/to/chat-with-blender/run_server.py"]
    }
  }
}

⚠️ Important: Replace C:/path/to/chat-with-blender/ with your own project path.

3. Restart Claude Desktop.

For LM Studio

1. Add the same configuration to LM Studio's mcp.json file:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["C:/path/to/chat-with-blender/run_server.py"]
    }
  }
}

2. Restart LM Studio.

---

💡 Usage

1. Start the Server in Blender

1. Open Blender
2. Go to View3D → Sidebar (N key) → BlenderMCP tab
3. Click the "Start Server" button
4. You should see Status: Running

<p align="center"> <img src="screenshots/blender-panel.png" alt="BlenderMCP Panel" width="600"> </p>

2. Start Chatting with AI

Start a new chat in Claude Desktop or LM Studio and give Blender commands:

<p align="center"> <img src="screenshots/chat-demo.png" alt="AI Chat Demo" width="600"> </p>

Example Prompts

"Add a red metallic cube to the scene"

"Create a blue sphere next to the cube and move it 2 units to the right"

"Clear the scene and set up a studio: 
 ground, 3-point lighting, and camera"

"Create an emissive green torus, make it glow"

"Give me a list of all objects in the scene"

"Render the scene at 1920x1080 resolution"

💡 Tip: To see materials, set the viewport shading mode to Material Preview or Rendered in Blender (Z key).

---

🛠️ MCP Tools

Tool	Description
get_scene_info	Get scene information (objects, frame info)
get_object_info	Get details of a specific object
create_object	Create new primitive object (cube, sphere, cylinder...)
create_text	Create 3D text
modify_object	Modify object position/rotation/scale
delete_object	Delete object
duplicate_object	Duplicate object
apply_material	Create and apply material
create_light	Add light (POINT, SUN, SPOT, AREA)
create_camera	Add camera
clear_scene	Clear the scene
set_background_color	Set background color
execute_blender_code	Execute custom Python code
render_image	Render image

---

🔒 Security

⚠️ Security Warning: This MCP server includes the execute_blender_code tool. This tool allows the AI to execute arbitrary Python code within Blender.

Security Recommendations

1. Use trusted AI models - Only use with AI assistants you trust
2. Localhost connection - Server runs on localhost by default
3. Backup your important files - Save your Blender projects regularly
4. Code review - Review the code that AI will execute beforehand

Network Security

• Server listens only on localhost:9876
• External access is disabled by default
• No firewall rules needed

---

🐛 Known Issues and Limitations

This is a vibe coding project. The following known issues/limitations exist:

Issue	Status	Workaround
Materials not visible in viewport	Expected behavior	Switch to Material Preview mode with Z key
Blender 5.0+ node compatibility issues	Fixed	Use latest addon.py
Performance for complex models	Known	Start with simple objects

If you find a new bug, please open an Issue!

---

🐛 Troubleshooting

"Could not connect to Blender"

• ✅ Make sure the addon is active in Blender
• ✅ Click "Start Server" in the BlenderMCP panel
• ✅ Check that port 9876 is not being used by another application

"ModuleNotFoundError: No module named 'blender_mcp'"

• ✅ Make sure you're using the full path to the run_server.py file
• ✅ Install Python dependencies: pip install mcp httpx

Materials not showing

• ✅ Set viewport shading mode to Material Preview or Rendered (Z key)

Claude Desktop not showing tools

• ✅ Check the path in the config file
• ✅ Completely close and restart Claude Desktop

---

📁 Project Structure

chat-with-blender/
├── addon.py              # Blender addon (socket server)
├── run_server.py         # MCP server launcher
├── pyproject.toml        # Python project configuration
├── README.md             # This file
├── LICENSE               # MIT License
├── screenshots/          # Screenshots
└── src/
    └── blender_mcp/
        ├── __init__.py
        └── server.py     # MCP server implementation

---

🤝 Contributing

This is a vibe coding project - your contributions will make it more stable!

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

We especially need:

• 🐛 Bug fixes
• 📝 Documentation improvements
• ✨ New MCP tools
• 🧪 Test coverage

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

🙏 Acknowledgments

• Anthropic - For the MCP protocol
• Blender Foundation - For the amazing 3D software
• Google DeepMind Gemini - For vibe coding assistance ✨
• All contributors

---

<p align="center"> <strong>⭐ Don't forget to star this project if you like it!</strong> </p>

<p align="center"> _{Made with 💜 and lots of vibes} </p>