<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

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

### Step 2: Install Python Dependencies

```bash
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:

```json
{
  "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:

```json
{
  "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](../../issues)!

---

## 🐛 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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Anthropic](https://anthropic.com) - For the MCP protocol
- [Blender Foundation](https://blender.org) - For the amazing 3D software
- [Google DeepMind Gemini](https://deepmind.google/technologies/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">
  <sub>Made with 💜 and lots of vibes</sub>
</p>