mcp-blender

Control Blender from any MCP client, with tools for modeling, materials, sculpting, animation,
AI 3D generation, and Microsoft Flight Simulator content.

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

Status, October 2026: a full audit found that many tools fail in real Blender, including
every MSFS tool, most bake tools, and a group of mesh tools. Fixes are landing now and are
tracked in the issues. Treat those areas
as not working until the next release.

What is mcp-blender?

mcp-blender is an MCP server for AI clients such as Claude Desktop, Claude Code, and Codex CLI.
The server speaks the Model Context Protocol over stdio. A Blender addon listens on a local TCP
socket and runs each command on Blender's main thread through bpy.app.timers.

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

• Blender coverage: scene, object, mesh, material, modifier, animation, render, export,
  baking, geometry nodes, sculpting, rigging, physics, and annotations.
• MSFS content: LOD, collision, material, animation, and livery tools for Microsoft Flight
  Simulator. This area is being rebuilt and does not work in the current release.
• AI 3D generation: text and image to 3D through Hyper3D Rodin, Meshy, Tripo, TripoSR,
  Stable Fast 3D, Hunyuan3D, and ComfyUI.
• Self-refinement loop: render an object from several angles, score it with an Ollama vision
  model, and iterate.
• Poly Haven: free HDRIs, textures, and models with no API key.

Quick start

1. Run the MCP server

The mcp-blender package on PyPI is an unrelated project, so install this one from GitHub.
With uv there is nothing to install up front:

uvx --from git+https://github.com/RFingAdam/mcp-blender mcp-blender --help

Or with pip:

pip install "mcp-blender @ git+https://github.com/RFingAdam/mcp-blender.git"

2. Install the Blender addon

Build the addon ZIP from source. Recent releases don't include one yet.

git clone https://github.com/RFingAdam/mcp-blender
cd mcp-blender
python scripts/package_addon.py
# creates dist/blender_mcp_addon-<version>.zip

In Blender, open Edit > Preferences > Add-ons, choose Install from Disk from the menu at
the top right, select the ZIP, and enable MCP Server Addon.

3. Configure your MCP client

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/RFingAdam/mcp-blender",
        "mcp-blender"
      ]
    }
  }
}

If you installed with pip, use "command": "mcp-blender" with no args.

4. Connect

1. In Blender's 3D viewport, press N and open the MCP Server tab.
2. Click Start Server.
3. Restart your MCP client. The Blender tools appear in its tool list.

Then try:

Create a red cube at (2, 0, 0), add a subdivision surface modifier with 2 levels, and render
it to /tmp/render.png.

Tools

The server defines 218 tools. This table lists what exists, not what has been verified to work;
see the status note above. The tool list is in docs/tools.md.

Every tool name takes a blender_ prefix, for example blender_scene_info.

Self-refinement loop

The agent writes mesh code, renders from several angles, an Ollama vision model scores the result,
and the agent applies fixes until the score stops improving.

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

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

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

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

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

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

See docs/usage.md for a walkthrough.

External integrations

Poly Haven

Poly Haven provides free HDRIs, textures, and 3D models with no API key.
Downloads are cached locally.

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

AI 3D model generation

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:

# TripoSR is not on PyPI: clone it and put it on PYTHONPATH
git clone https://github.com/VAST-AI-Research/TripoSR
pip install -r TripoSR/requirements.txt
export PYTHONPATH="$PWD/TripoSR:$PYTHONPATH"

ollama pull llama3.2-vision:11b   # vision model for evaluation and refinement

Usage:

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

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

Security

The addon's socket has no authentication yet, and blender_execute_script runs arbitrary Python
inside Blender. Any process on your machine that can reach the port can run code as you.

• Only start the server on a machine you trust, and stop it when you're done.
• Keep the host set to localhost. Don't bind it to 0.0.0.0 or expose port 9876.
• Don't run untrusted prompts or scripts against a Blender session with work you care about.

Authentication and a Python execution switch are planned for the next stable release
(#12).

Configuration

mcp-blender [--host HOST] [--port PORT]

  --host HOST   Blender addon host (default: 127.0.0.1)
  --port PORT   Blender addon port (default: 9876)

The MCP Server tab in Blender's sidebar sets the socket port and starts or stops the server.

Blender versions

Blender 4.5 LTS and 5.2 LTS are tested on every pull request. Blender 4.2 LTS is tested nightly on a
best-effort basis.

Troubleshooting

"Connection refused": make sure Blender is running, the MCP Server tab shows the server
running, and the port matches.

"Tool not found": restart your MCP client after editing its config, confirm the server command
runs on its own with --help, and check the client's MCP log.

Addon doesn't appear in Blender: check Blender's system console for errors and try reinstalling
the ZIP.

Poly Haven downloads fail: check your connection, confirm the asset ID exists on polyhaven.com,
and check disk space.

AI generation doesn't work: blender_ai_list_backends shows backend status. Check your API keys
for cloud backends, or your models and VRAM for local ones. Follow a job with
blender_ai_model_status.

Documentation

• Quick start: install through first call.
• Tool reference: tools grouped by stage.
• Usage examples: self-refinement, MSFS, and livery walkthroughs.
• Architecture: how the server and addon fit together.
• MSFS roadmap: planned MSFS workflow.

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]"

pytest tests/ --ignore=tests/blender_integration_test.py   # unit tests
python -m tests.harness.driver --help   # truth harness, needs Blender; see CONTRIBUTING.md
ruff check .
ruff format .
python scripts/package_addon.py   # builds the addon ZIP

Contributions are welcome. See CONTRIBUTING.md.

License

AGPL-3.0-or-later.

Trademarks

This project is not affiliated with, endorsed by, or sponsored by the Blender Foundation.
"Blender" is a trademark of the Blender Foundation, used here only to identify the software this
project works with.

Acknowledgments

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