Blender MCP Bridge

You can remotely control Blender through the Model Context Protocol (MCP) using the Blender MCP Bridge. This setup lets an MCP client send images to generate colored 3D models, execute Blender Python scripts, and query scene information in real time, all while maintaining a safe, thread-safe connection between the client and Blender.

How to use

This server enables MCP clients to interact with Blender by running a local TCP server inside Blender and exposing an external MCP interface through an Antigravity or other MCP-compatible client. You can create 3D content from images, execute Python scripts inside Blender, and request scene details. Start the Blender server, ensure the MCP client connects, and then issue high-level actions like creating content or running scripts without needing to operate Blender directly.

Typical usage patterns include starting Blender with the socket server, connecting an MCP client, and asking for content creation or script execution. For example, ask your client to generate a scene from an image or to run a predefined Python script that builds or modifies objects in Blender.

How to install

Prerequisites you need before installing are Python 3.10 or newer, Blender 4.2 or newer with a fully accessible path, and pip as the Python package manager.

Step 1: Clone the project repository.

Step 2: Create and activate a virtual environment.

Step 3: Install dependencies from the requirements file.

Step 4: (Optional) Install the package in editable mode for development.

Exact commands you should run are shown below. Copy each line exactly and run in your shell, adjusting paths to your environment.

# Clone the repository
git clone https://github.com/MITHRAN-BALACHANDER/Blender-MCP-antigravity.git
cd Blender-MCP-antigravity

# Create and activate a virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration and MCP server setup

You configure the MCP integration in your Antigravity MCP server setup by adding one or more server configurations that point to the Blender MCP bridge. The following local (stdio) configurations run the server as a Python script from your filesystem.

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["C:/path/to/Blender-MCP-antigravity/antigravity_blender_server.py"],
      "env": {}
    }
  }
}

Additional usage notes

If you prefer using a virtual environment for the Python interpreter, you can point to the venv Python executable and run the same server script.

{
  "mcpServers": {
    "blender": {
      "command": "C:/path/to/Blender-MCP-antigravity/venv/Scripts/python.exe",
      "args": ["C:/path/to/Blender-MCP-antigravity/antigravity_blender_server.py"],
      "env": {}
    }
  }
}

Troubleshooting

If the connection fails or you encounter timeouts, ensure Blender is running with the server script and that port 8081 is accessible. Check the Blender console for errors, confirm that the Python script defines and calls main(), and ensure progress updates are sent via status calls during long tasks.

# Ensure the Blender server is running
"C:/Program Files/Blender Foundation/Blender 4.2/blender.exe" --background --python blender_server.py

# Check port usage (Windows example)
netstat -an | findstr 8081
```,

Examples

Here are practical commands to try after you have the environment set up. Activate your virtual environment, then run example scripts through the bridge.

# Activate venv first
.\venv\Scripts\activate

# Run an example script through the bridge (adjust paths as needed)
python run_via_bridge.py generate_island.py
```,

MCP tools reference

The server exposes several MCP tools to perform common tasks. Each tool is described below so you can call them from your MCP client.

image_to_3d_model creates a 3D model from an image using extracted colors.

blender_exec runs Python code inside Blender and returns results and statuses.

get_blender_scene queries the current Blender scene and returns objects, meshes, materials, and collections.

Project structure

The project includes sources for the MCP bridge, the Blender socket server, sample addons, and example scripts to demonstrate content creation and image-based modeling.

Common files include the MCP bridge server, the Blender server, and utilities to run scripts through the bridge.

Contributing

Contributions are welcome. Use a feature branch, implement changes, and open a pull request to share improvements.

License

This project is released under the MIT License.

Links

Blender MCP Bridge connects Blender with the Model Context Protocol via Antigravity and MCP-compatible clients for AI-driven content creation.

Available tools

image_to_3d_model

Create a 3D model with colors extracted from an image. Provides a base64 image input and optional model type and name, returning an object name and the derived colors.

blender_exec

Execute Python code inside Blender via MCP and receive status updates and results.

get_blender_scene

Query the current Blender scene to retrieve objects, meshes, materials, and collections.