> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-for-blender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Blender MCP Works: Architecture and Protocol

> Blender MCP uses two components — a Blender addon and a Python MCP server — communicating over a TCP socket with a JSON protocol.

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:

<CardGroup cols={2}>
  <Card title="Blender Addon" icon="desktop">
    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`).
  </Card>

  <Card title="MCP Server" icon="server">
    A Python process that implements the Model Context Protocol. It connects to the Blender addon and exposes Blender tools to your AI client.
  </Card>
</CardGroup>

## 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.

<Note>
  The default socket address is `localhost:9876`. You can change this with the `BLENDER_HOST` and `BLENDER_PORT` environment variables.
</Note>

A command is a JSON object with a `type` and `params`:

```json theme={null}
{
  "type": "get_scene_info",
  "params": {}
}
```

A response is a JSON object with a `status` and either a `result` or `message`:

```json theme={null}
{
  "status": "success",
  "result": { ... }
}
```

<Warning>
  All operations time out after 180 seconds. Long-running tasks may need to be split into smaller steps.
</Warning>

## 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.

<Tip>
  Prefer high-level tools when available. Use `execute_blender_code` only for operations that are not covered by the built-in tools.
</Tip>

## Security Model

<Warning>
  `execute_blender_code` runs arbitrary Python inside Blender. Always save your work before using this tool.
</Warning>

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.