Skip to main content
Blender MCP bridges your AI client and Blender through two cooperating components. Understanding the architecture helps you diagnose connection issues and reason about what is and is not possible.

​
Two Components

Blender MCP is made up of two parts that work together:

Blender Addon

Runs inside Blender as a socket server on localhost:9876. It receives JSON commands and executes them directly in Blender using the Blender Python API (bpy).

MCP Server

A Python process that implements the Model Context Protocol. It connects to the Blender addon and exposes Blender tools to your AI client.

​
Communication Flow

When you send a prompt, the request flows through the system in this order:
  1. The AI client calls a tool on the MCP server.
  2. The MCP server sends a JSON command over TCP to the Blender addon.
  3. The addon executes Blender Python (bpy) inside the running Blender instance.
  4. The addon returns the result back to the MCP server.
  5. The MCP server forwards the result back to the AI client.
This happens transparently in real time while Blender is running with a GUI.

​
Communication Protocol

Commands and responses are exchanged as JSON objects over a TCP socket.
The default socket address is localhost:9876. You can change this with the BLENDER_HOST and BLENDER_PORT environment variables.
A command is a JSON object with a type and params:
A response is a JSON object with a status and either a result or message:
All operations time out after 180 seconds. Long-running tasks may need to be split into smaller steps.

​
Tool Execution Flow

Blender MCP exposes two categories of tools: High-level tools such as get_scene_info, get_object_info, get_viewport_screenshot, and download_polyhaven_asset are purpose-built for common tasks. They send structured commands to the addon, which runs predefined bpy logic and returns clean results. Low-level code execution via execute_blender_code sends raw Python directly to Blender. This gives unlimited flexibility but also full access to the Blender environment, including the file system.
Prefer high-level tools when available. Use execute_blender_code only for operations that are not covered by the built-in tools.

​
Security Model

execute_blender_code runs arbitrary Python inside Blender. Always save your work before using this tool.
Blender MCP is designed for local use. The addon listens on localhost only, which means it is not reachable from other machines by default. Do not expose port 9876 publicly or run Blender MCP on an untrusted network. Only one MCP server instance should connect to Blender at a time. Running multiple clients (for example, both Cursor and Claude Desktop) simultaneously against the same Blender session will cause conflicts.