MCP 服务器

Chat with Blender

Enables AI assistants to control Blender 3D modeling and rendering through natural language commands via the Model Context Protocol.

README

<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"> <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"> <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

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

Step 4: MCP Client Configuration

For Claude Desktop

Open the config file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
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.

Restart Claude Desktop.

For LM Studio

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"]
    }
  }
}

Restart LM Studio.

💡 Usage

1. Start the Server in Blender

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

2. Start Chatting with AI

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

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

Use trusted AI models - Only use with AI assistants you trust
Localhost connection - Server runs on localhost by default
Backup your important files - Save your Blender projects regularly
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!

Fork the project
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push the branch (git push origin feature/amazing-feature)
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"> <sub>Made with 💜 and lots of vibes</sub> </p>