MCP for Blender 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
MCP for Blender is made up of two parts that work together:
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).
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:
- The AI client calls a tool on the MCP server.
- The MCP server sends a JSON command over TCP to the Blender addon.
- The addon executes Blender Python (
bpy) inside the running Blender instance. - The addon returns the result back to the MCP server.
- 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:
{
"type": "get_scene_info",
"params": {}
}A response is a JSON object with a status and either a result or message:
{
"status": "success",
"result": { ... }
}All operations time out after 180 seconds. Long-running tasks may need to be split into smaller steps.
Tool Execution Flow
MCP for Blender 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.
MCP for Blender is designed for local use. The addon listens on localhost only, which means it is not reachable from other machines by default. The socket has no authentication or encryption, so anyone who can reach the port can run Python inside Blender. Do not expose port 9876 publicly or run MCP for Blender on an untrusted network; to reach a remote Blender, prefer an SSH tunnel over pointing BLENDER_HOST at it directly.
To restrict what execute_blender_code can do, enable safe mode with BLENDER_MCP_SAFE_MODE=1. Every script is checked before it runs, and risky code (direct file access, running other programs, network access) is blocked.
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.