Blend AI MCP Server

blend-ai

The most intuitive and efficient MCP Server for Blender. Control Blender entirely through AI assistants like Claude — create 3D models, set up scenes, animate, render, and more, all through natural language.

<small>This was created via Claude Code using the Haiki model and 20 random reference images. It took 5 minutes:</small>

Key Features

• 108 tools covering every major Blender domain: modeling, materials, lighting, camera, animation, rendering, sculpting, UV mapping, physics, geometry nodes, rigging, curves, collections, file I/O, and viewport control
• No arbitrary code execution — every operation is an explicit, validated, parameterized tool. No exec(), no eval(), no script injection vectors.
• Zero-dependency Blender addon — the addon uses only Python stdlib + bpy. Nothing to pip install inside Blender's bundled Python.
• Thread-safe architecture — background TCP server with queue-based main-thread execution, respecting Blender's single-threaded API constraint.
• MCP resources — browse scene objects, materials, and scene info as structured context.
• Workflow prompts — pre-built prompt templates for common tasks (product shots, character base meshes, scene cleanup, turntable animations).

Quickstart

1. Install the MCP server

git clone https://github.com/jabberwock/blend-ai.git
cd blend-ai
uv pip install -e .

2. Install the Blender addon

1. Open Blender (5.0+)
2. Go to Edit > Preferences > Add-ons > Install...
3. Select the addon/ folder from this repo (or zip it first)
4. Enable "blend-ai" in the addon list

Alternatively, symlink for development:

# macOS
ln -s "$(pwd)/addon" ~/Library/Application\ Support/Blender/5.0/scripts/addons/blend_ai

# Linux
ln -s "$(pwd)/addon" ~/.config/blender/5.0/scripts/addons/blend_ai

# Windows (run as admin)
mklink /D "%APPDATA%\Blender Foundation\Blender\5.0\scripts\addons\blend_ai" "%cd%\addon"

Then enable the addon in Blender preferences.

3. Start the server in Blender

In Blender's 3D Viewport, open the N-panel (press N), find the blend-ai tab, and click Start Server. The addon listens on 127.0.0.1:9876.

4. Connect your AI assistant

This repo includes an `mcp.json` config file you can use directly or copy into your client's configuration.

Claude Code Integration

claude mcp add blend-ai -- uv run --directory /path/to/blend-ai blend-ai

Replace /path/to/blend-ai with the actual path to your clone. Make sure Blender is running with the addon server started before using the tools.

Usage

$ claude

> Create a red metallic sphere on a white plane with three-point lighting

> Add a subdivision surface modifier to the sphere and set it to level 3

> Set up a turntable animation and render it to /tmp/turntable/

Claude Desktop Integration

Add blend-ai to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "blend-ai": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blend-ai", "blend-ai"]
    }
  }
}

Replace /path/to/blend-ai with the actual path to your clone. Or copy the contents of the bundled `mcp.json` into your config file.

Restart Claude Desktop. The Blender tools will appear in the tool list.

Other MCP Clients

blend-ai is a standard MCP server using stdio transport. Any MCP-compatible client can connect using the `mcp.json` config or by running the server directly:

uv run --directory /path/to/blend-ai blend-ai
# or: python -m blend_ai.server

The server communicates over stdin/stdout using the MCP protocol. It connects to Blender's addon over TCP on 127.0.0.1:9876.

Architecture

AI Assistant <--stdio/MCP--> blend-ai server <--TCP socket--> Blender addon <--bpy--> Blender

• MCP Server (src/blend_ai/): Python process using the mcp SDK. Exposes tools, resources, and prompts over stdio. Validates all inputs before forwarding to Blender.
• Blender Addon (addon/): Runs a TCP socket server inside Blender on a background thread. Commands are queued and executed on the main thread via bpy.app.timers to respect Blender's threading model.
• Protocol: Length-prefixed JSON messages over TCP. Each message is a 4-byte big-endian length header followed by a UTF-8 JSON payload.

Tool Domains