mcp-blender

Control Blender from any MCP client — 218 tools across modeling, materials, sculpting, animation, AI 3D generation, and MSFS content creation.
Drive it from your IDE, terminal, or AI agent and run an iterative render-analyze-refine loop without leaving Blender.

Quick start ·
Tools ·
Self-refinement loop ·
Workflows ·
Documentation

Supports Blender 4.2 LTS and Blender 5.0.

What is mcp-blender?

mcp-blender is an MCP server that exposes 218 Blender tools to any
MCP-compatible AI client (Claude Desktop, Claude Code, Codex CLI, …).
The MCP server speaks the Model Context Protocol over stdio; a Blender
addon listens on a local TCP socket and dispatches into Blender's
bpy API on the main thread via bpy.app.timers.

┌─────────────────┐    stdio     ┌─────────────────┐   TCP/JSON-RPC   ┌─────────────────┐
│  MCP client     │ ◄──────────► │   MCP Server    │ ◄──────────────► │  Blender Addon  │
│  (Claude / …)   │              │  (Python proc)  │   port 9876      │  (bpy.app.timers)│
└─────────────────┘              └─────────────────┘                  └─────────────────┘

What it does well:

• 🤖 AI-native via MCP. First-class Model Context Protocol
  server with 218 tools across every Blender pipeline stage.
• 🎨 End-to-end coverage. Scene, object, mesh, material, modifier,
  animation, render, export, baking, geometry nodes, sculpting, rigging,
  physics, annotations.
• ✈️ MSFS-ready. Full Microsoft Flight Simulator 2020 / 2024
  content pipeline: LOD hierarchies, collision meshes, MSFS materials,
  animation tags, livery painting + transfer for FBW / Fenix / PMDG /
  iniBuilds / Aerosoft.
• 🧠 AI 3D generation. Multi-backend (Hyper3D Rodin, Meshy, Tripo,
  TripoSR, Stable Fast 3D, Hunyuan3D, ComfyUI) text/image-to-3D with
  auto mesh cleanup and decimation.
• 🔁 Self-refinement loop. render_multi_angle → analyze_viewport
  → refine_iteration against an Ollama vision model converges geometry
  toward a target prompt.
• 🪨 Poly Haven built-in. Free HDRIs, textures, and models with no
  API key.
• 🔒 MIT licensed.

Quick start

1. Install the MCP server

pip install mcp-blender

Or from source:

git clone https://github.com/RFingAdam/mcp-blender
cd mcp-blender
pip install -e .

2. Install the Blender addon

Option A — from ZIP (recommended):

1. Download blender_mcp_addon.zip from the releases page.
2. In Blender: Edit → Preferences → Add-ons → Install…
3. Select the ZIP, enable "MCP Server Addon".

Option B — from source:

# Linux
ln -s /path/to/mcp-blender/addon/blender_mcp_addon \
      ~/.config/blender/4.2/scripts/addons/

# macOS
ln -s /path/to/mcp-blender/addon/blender_mcp_addon \
      ~/Library/Application\ Support/Blender/4.2/scripts/addons/

# Windows (admin)
mklink /D "%APPDATA%\Blender Foundation\Blender\4.2\scripts\addons\blender_mcp_addon" ^
       "C:\path\to\mcp-blender\addon\blender_mcp_addon"

Then enable the addon in Blender preferences.

3. Configure your MCP client

{
  "mcpServers": {
    "blender": {
      "command": "mcp-blender",
      "args": ["--port", "9876"]
    }
  }
}

4. Three surfaces, same loop

Tools

218 MCP tools, grouped by Blender pipeline stage. Full grouped
reference (with source links) in docs/tools.md.

Full per-tool argument tables: docs/tools.md. All
tool source lives under
src/mcp_blender/
(server side) and
addon/blender_mcp_addon/
(Blender side).

Self-refinement loop

mcp-blender ships an iterative render-analyze-fix loop. The agent
generates mesh code, renders from multiple angles, an Ollama vision
model scores the result, and the agent applies fixes until the score
converges.

┌───────────┐  execute_script  ┌─────────┐  render_multi_angle  ┌──────────────┐
│  agent    │ ──────────────► │ Blender  │ ───────────────────► │  PNG images  │
│  (LLM)    │                 │  (bpy)   │                      └──────┬───────┘
└─────┬─────┘                 └─────────┘                              │
      │                                                  analyze_viewport
      │  apply fix                                                     │
      │  (loop)                                                        ▼
      │                                                     ┌──────────────────┐
      └─────────────────────────────────────────────────────│  Ollama Vision   │
                              feedback + score              │  (llama3.2-11b)  │
                                                            └──────────────────┘

Skeleton call sequence:

# 1. Open a refinement session
blender_refine_create_session(object_name="Tree", prompt="A realistic low-poly pine tree")

# 2. Generate initial mesh
blender_execute_script(script="import bmesh; ...")

# 3. Iterate
blender_refine_iteration(object_name="Tree", iteration=0, max_iterations=5)

# 4. Apply fixes from feedback, iterate again
blender_execute_script(script="# fix issues from analysis ...")
blender_refine_iteration(object_name="Tree", iteration=1, previous_score=0.6)

# 5. Inspect session
blender_refine_get_session(session_id="...")

See docs/usage.md for a full walkthrough.

External integrations

Poly Haven

Poly Haven provides free HDRIs, textures, and
3D models. No API key required.

blender_polyhaven_search(query="brick", asset_type="textures")
blender_polyhaven_download(asset_id="brick_wall_001", resolution="2k")

Assets are cached locally.

AI 3D model generation

Multi-backend text/image-to-3D — cloud APIs and local models.

Cloud setup:

export RODIN_API_KEY="your-rodin-key"
export MESHY_API_KEY="your-meshy-key"
export TRIPO_API_KEY="your-tripo-key"

Local setup:

pip install triposr     # fast image-to-3D
ollama pull llava       # vision model

Usage:

blender_ai_generate_model(prompt="a wooden chair", style="realistic")
blender_ai_generate_model(image_path="/path/to/image.png", backend="triposr")
blender_ai_model_status(job_id="abc123", auto_import=true, optimize_mesh=true)

Supported styles: realistic, cartoon, low_poly, sculpture, anime.
Formats: glb (default), gltf, fbx, obj, usdz.

Workflows

mcp-blender is a creative-tooling tangent in
eng-mcp-suite — it doesn't
fit the engineering compliance loop directly, but it shares brand,
docs, and MCP wiring with the rest of the family.

Part of eng-mcp-suite.

Documentation

• 📘 Quick Start — install through first call.
• 🛠️ Tool reference — all 218 tools grouped by stage.
• 📐 Usage examples — end-to-end walkthroughs (self-refine, MSFS, livery).
• 🏗️ Architecture — how this MCP fits in eng-mcp-suite.
• ✈️ MSFS roadmap — MSFS content workflow.

Part of eng-mcp-suite

_{This MCP server is part of}

_{An open umbrella for engineering MCP servers across RF, EMC, PCB,
signal integrity, EM simulation, and lab test. Same brand, same docs
structure, designed to compose. See the
full catalog
or jump to a sibling:}

Configuration

MCP server

mcp-blender --help

Options:
  --host TEXT   Blender addon host  [default: localhost]
  --port INT    Blender addon port  [default: 9876]

Blender addon panel

In the 3D viewport sidebar:

• Port — TCP port for the socket server (default 9876).
• Start / Stop Server — toggle the MCP socket server.

Version compatibility

The addon ships a compatibility layer for Blender API differences:

The layer handles these differences automatically.

Troubleshooting

"Connection refused" — make sure Blender is running, the MCP Server
panel shows "Server running", the port matches, and the firewall allows
local TCP on 9876.

"Tool not found" — restart Claude / Codex after editing the MCP
config; verify mcp-blender --help runs; check the client's MCP server
log.

Addon not appearing in Blender — check Blender's system console for
errors; verify Python version (Blender 4.2+ uses Python 3.11+); try
reinstalling.

Poly Haven downloads fail — check connectivity; verify the asset
ID exists on polyhaven.com; check disk space.

AI generation not working — blender_ai_list_backends shows status;
verify API keys (RODIN_API_KEY, MESHY_API_KEY, TRIPO_API_KEY) for
cloud; verify models / VRAM for local; monitor with
blender_ai_model_status; check history with blender_ai_get_history.

Development

git clone https://github.com/RFingAdam/mcp-blender
cd mcp-blender
python -m venv .venv
source .venv/bin/activate   # .venv\Scripts\activate on Windows
pip install -e ".[dev]"

Tests:

pytest tests/ --ignore=tests/blender_integration_test.py
blender --background --python tests/blender_integration_test.py

Lint:

ruff check .
ruff format .

Build the addon ZIP:

python scripts/package_addon.py
# → dist/blender_mcp_addon-<version>.zip

Contributing

Contributions are welcome. Fork, branch, add tests, open a PR.
See CONTRIBUTING.md.

License

AGPL-3.0-or-later. Relicensed from MIT in v0.4.0 to align
with the eng-mcp-suite toolkit-wide AGPL move. The underlying Blender
application remains GPL-3.0+ and is invoked at runtime, not redistributed
by this wrapper.

Acknowledgments

• Blender Foundation — for Blender itself.
• Poly Haven — for free 3D assets.
• Hyper3D Rodin, Meshy.ai, Tripo, TripoSR, Stable Fast 3D, Hunyuan3D, ComfyUI — AI 3D backends.
• The MCP working group — for the Model Context Protocol specification.