BlenderMCP connects Blender to Codex through the Model Context Protocol (MCP), allowing Codex to directly interact with and control Blender. This integration enables prompt assisted 3D modeling, scene creation, and manipulation.

We have no official website. Any website you see online is unofficial and has no affiliation with this project. Use them at your own risk.

Full tutorial

Give feedback, get inspired, and build on top of the MCP: Discord

CodeRabbit

Satish Goda

All supporters:

Support this project

• Added Hunyuan3D support

• View screenshots for Blender viewport to better understand the scene
• Search and download Sketchfab models
• Support for Poly Haven assets through their API
• Support to generate 3D models using Hyper3D Rodin
• Run Blender MCP on a remote host
• Telemetry for tools executed (completely anonymous)

• For newcomers, you can go straight to Installation. For existing users, see the points below
• Download the latest addon.py file and replace the older one, then add it to Blender
• Update the Codex MCP server entry in your config (see the Codex setup section) and you should be good to go!

• Two-way communication: Connect Codex to Blender through a socket-based server
• Object manipulation: Create, modify, and delete 3D objects in Blender
• Material control: Apply and modify materials and colors
• Scene inspection: Get detailed information about the current Blender scene
• Code execution: Run arbitrary Python code in Blender from Codex

The system consists of two main components:

1. Blender Addon (addon.py): A Blender addon that creates a socket server within Blender to receive and execute commands
2. MCP Server (src/blender_mcp/server.py): A Python server that implements the Model Context Protocol and connects to the Blender addon

• Blender 3.0 or newer
• Python 3.10 or newer
• uv package manager:
• Codex CLI runs on macOS and Linux, or Windows 11 via WSL2. If you are on Windows, install and use Codex inside WSL2.

If you're on Mac, please install uv as

brew install uv

On Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 

and then add uv to the user path in Windows (you may need to restart Codex afterward):

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

Otherwise installation instructions are on their website: Install uv

Note: Do not proceed before installing UV.

The following environment variables can be used to configure the Blender connection:

• BLENDER_HOST: Host address for Blender socket server (default: "localhost")
• BLENDER_PORT: Port number for Blender socket server (default: 9876)

Example:

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

Install Codex CLI and sign in first. See the Codex docs: https://developers.openai.com/codex

Configure the MCP server in ~/.codex/config.toml using the Codex MCP format:

[mcp_servers.blender]
command = "uvx"
args = ["blender-mcp"]

If you are using the Codex IDE extension in VS Code, Cursor, or Windsurf, install it first: https://developers.openai.com/codex/ide

Then open the Codex MCP settings from the extension, and add the same mcp_servers.blender configuration shown above in the config.toml. Common locations are ~/.codex/config.toml on macOS and Linux, and /home/<user>/.codex/config.toml inside WSL2.

For Mac users, go to Settings > MCP and paste the following

• To use as a global server, use "add new global MCP server" button and paste
• To use as a project specific server, create .cursor/mcp.json in the root of the project and paste

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

For Windows users, go to Settings > MCP > Add Server, add a new server with the following settings:

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "blender-mcp"
            ]
        }
    }
}

Cursor setup video

Note: Only run one MCP client at a time, for example Codex CLI or Cursor.

Prerequisites: Make sure you have Visual Studio Code installed before proceeding.

1. Download the addon.py file from this repo
2. Open Blender
3. Go to Edit > Preferences > Add-ons
4. Click "Install..." and select the addon.py file
5. Enable the addon by checking the box next to "Interface: Blender MCP"

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Turn on the Poly Haven checkbox if you want assets from their API (optional)
4. Click "Connect to Codex"
5. Make sure the MCP server is running in your terminal

Once the Codex config file has been set and the addon is running in Blender, you will see a hammer icon with tools for the Blender MCP.

• Get scene and object information
• Create, delete and modify shapes
• Apply or create materials for objects
• Execute any Python code in Blender
• Download the right models, assets and HDRIs through Poly Haven
• AI generated 3D models through Hyper3D Rodin

Here are some examples of what you can ask Codex to do:

• "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" Demo
• "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" Demo
• Give a reference image, and create a Blender scene out of it Demo
• "Generate a 3D model of a garden gnome through Hyper3D"
• "Get information about the current scene, and make a threejs sketch from it" Demo
• "Make this car red and metallic"
• "Create a sphere and place it above the cube"
• "Make the lighting like a studio"
• "Point the camera at the scene, and make it isometric"

Hyper3D's free trial key allows you to generate a limited number of models per day. If the daily limit is reached, you can wait for the next day's reset or obtain your own key from hyper3d.ai and fal.ai.

• Connection issues: Make sure the Blender addon server is running, and the MCP server is configured in Codex. Do not run the uvx command in the terminal. Sometimes, the first command will not go through but after that it starts working.
• Timeout errors: Try simplifying your requests or breaking them into smaller steps
• Poly Haven integration: Results can be erratic depending on the request
• Have you tried turning it off and on again?: If you're still having connection errors, try restarting both Codex and the Blender server

The system uses a simple JSON-based protocol over TCP sockets:

• Commands are sent as JSON objects with a type and optional params
• Responses are JSON objects with a status and result or message

• The execute_blender_code tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments. ALWAYS save your work before using it.
• Poly Haven requires downloading models, textures, and HDRI images. If you do not want to use it, please turn it off in the checkbox in Blender.
• Complex operations might need to be broken down into smaller steps

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

This is a third-party integration and not made by Blender. Made by Siddharth