# mcp-for-blender 2.3.1: Connect AI Agents to Blender in One Command

> Source: <https://byteiota.com/mcp-for-blender-2-3-1-connect-ai-agents-blender/>
> Published: 2026-11-19 22:07:17+00:00

**Key takeaway:** mcp-for-blender 2.3.1 exposes nine tools over a localhost:9876 TCP socket so an agent executes bpy code directly in a running Blender instance, and because execute_blender_code is unsandboxed by default, setting BLENDER_MCP_SAFE_MODE=1 is the documented mitigation for the exploitable risk in GitHub

mcp-for-blender — the community MCP server with 35,000 GitHub stars and 4 million PyPI downloads — released version 2.3.1 on November 18, 2026. If you use Claude Code, Cursor, or Codex, you can now wire your AI coding agent directly into Blender’s Python runtime with a single command. The setup is fast. The use cases are real. And there is one security risk you need to understand before you go further.

## How It Works (The Architecture Matters)

Most AI-to-3D tools work by generating a mesh file and handing it back to you. mcp-for-blender does something different: it gives your agent a live, two-way connection to Blender itself.

The system has two components. A Python addon runs inside Blender and opens a TCP socket server on `localhost:9876`. The [MCP server on PyPI](https://pypi.org/project/mcp-for-blender/) bridges your AI client to that socket. When your agent calls a tool, the MCP server sends a JSON command over TCP, and the addon executes `bpy` (Blender’s Python API) inside your running Blender instance. The agent isn’t generating a file — it’s driving Blender’s Python runtime in real time, with feedback available on every call.

Nine tools are exposed to the AI client. The most used is `execute_blender_code`, which sends Python directly to Blender. `get_scene_info` returns a compact scene summary. `look` takes a viewport screenshot so the agent can verify what it built. `generate_3d` pulls a mesh from Tripo, Hunyuan3D, Meshy, or Hyper3D Rodin and imports it in one call. `generate_gaussian_world` — added in 2.3.0 — creates explorable environments via World Labs.

## Setup: Three Steps

Getting running takes about five minutes.

**Step 1: Install the MCP server.** The universal installer handles Claude Code, Cursor, Codex, VS Code, and Windsurf at once:

```
uvx mcp-for-blender setup
```

For Claude Code only:

```
claude mcp add blender uvx mcp-for-blender
```

For Cursor, add this to `.cursor/mcp.json` in your project root:

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

**Step 2: Enable the Blender addon.** Run `uvx mcp-for-blender install-addon`, then in Blender go to Edit → Preferences → Add-ons and enable **Interface: MCP for Blender**.

**Step 3: Start the server.** In Blender’s 3D Viewport, press **N** to open the side panel. Open the MCP for Blender tab and click **Start MCP Server**.

## What It Can Actually Do

- **Scene assembly.** Describe a scene and the agent sources assets from Poly Haven, Sketchfab, or Poly Pizza, imports them, positions them, and sets up lighting — without you touching the Blender UI.
- **Material generation.** Describe a material in prose (“worn concrete with water stains”) and the agent builds a full shader node tree in Blender’s node editor. Faster than building nodes by hand for standard materials.
- **Rigging boilerplate.** Bone creation, weight painting setup, constraint linking — the mechanical parts of rigging that everyone dreads.
- **Batch operations.** Rename hundreds of objects by convention. Convert legacy materials to Principled BSDF. Adjust UV scales across an entire scene.

The limits are real. The agent writes valid Python but does not understand topology — edge flow, subdivision readiness, and mesh quality for animation are not in scope. For anything requiring artistic judgment, treat the agent as a fast assistant that handles the mechanical parts.

## The Security Risk You Should Not Skip

`execute_blender_code` runs arbitrary Python inside Blender with no sandboxing by default. Because `bpy` has access to Python’s full standard library — including `os`, `subprocess`, and `socket` — a malicious prompt or prompt injection attack could execute arbitrary system commands on your machine. [GitHub issue #201](https://github.com/ahujasid/mcp-for-blender/issues/201) confirmed this as exploitable, not theoretical.

The fix is a one-line environment variable:

```
export BLENDER_MCP_SAFE_MODE=1
```

Safe mode blocks file I/O, subprocess calls, network access, and persistent code installation. Set it before you start the server. In any shared or networked environment, treat this as non-optional.

## Community vs. Official Blender MCP

The [Blender Foundation’s official MCP server](https://projects.blender.org/lab/blender_mcp) (v1.0.3) shipped in April 2026. It is simpler, more trustworthy from a security standpoint, and installs with one click — but it requires Blender 5.1 or newer and has no built-in generative AI integrations.

mcp-for-blender works with Blender 3.0 and up, supports every major AI client, and includes Tripo, Meshy, Hunyuan3D, and World Labs integrations out of the box. If you are on Blender 5.1 and doing primarily inspection and automation, the official server is worth considering. Everyone else is on the [community version](https://github.com/ahujasid/mcp-for-blender).

At 35,000 GitHub stars and 4 million downloads, mcp-for-blender is effectively the standard. The 2.3.1 release is a good moment to get started if you have been watching from the sidelines.
