Local-first Model Context Protocol (MCP) server for controlling a live
Blender session from AI agents, with a provider-agnostic LLM backend:
Ollama
LM Studio
llama.cpp server
OpenAI (and every OpenAI-compatible endpoint: vLLM, TGI, OpenRouter,
Groq, Together, Azure AI Foundry via its OpenAI-compatible surface, …)
MCP for Blender Using Open Weights Models
Sterne
122
Tools
—
Uptime
—
any server that speaks POST /chat/completions with an optional base URL
and API key
Providers are configured at startup (CLI flags or environment variables) and
can be switched at runtime through MCP tools, so an agent can hop between
backends without restarting the server.
Scene / object control (forwarded to the Blender add-on over TCP):
blender_get_scene_info, blender_get_object_info, blender_create_object,
blender_modify_object, blender_delete_object, blender_set_material,
blender_render_image, blender_execute_code.
blender_configure_llm – provider-switching instructions with examples.
Prompts are registered in src/blender_open_mcp/prompts.py.
Runtime provider switching (examples)
# Switch to LM Studio
tool blender_set_llm_provider {"provider":"lmstudio","base_url":"http://localhost:1234/v1","model":"local-model"}
# Switch to llama.cpp
tool blender_set_llm_provider {"provider":"llamacpp","base_url":"http://localhost:8080/v1"}
# Back to Ollama
tool blender_set_llm_provider {"provider":"ollama","base_url":"http://localhost:11434","model":"llama3.2"}
Azure AI Foundry (worked example)
Azure's OpenAI-compatible endpoint is deployment-scoped, so three values from
your Azure AI Foundry project are required — all of them go into the extra
parameter, and the model you name in model must match the deployment name:
Resource name — in the Azure portal, open your resource (e.g.
Azure OpenAI or AI Foundry project) and take the short name from its
endpoint URL: https://<resource>.openai.azure.com/....
Deployment name — on the Deployments page, e.g. gpt-4o-mini.
This is what you pass as model (it is not the base model name).
API key — on the resource's Keys and Endpoint page.
API version (optional) — e.g. 2024-06-01 (the adapter defaults to it).
Switch to Azure at runtime with a single call (CLI form):
import asyncio
from blender_open_mcp.client.client import BlenderMCPClient
async def main():
async with BlenderMCPClient("http://localhost:8000") as c:
# Switch to Azure AI Foundry
print(await c.set_llm_provider(
provider="azure",
api_key="YOUR_AZURE_API_KEY",
model="gpt-4o-mini",
extra={
"resource": "my-openai-resource",
"deployment": "gpt-4o-mini",
"api_version": "2024-06-01",
},
))
# Confirm the active config (API key is masked)
print(await c.get_llm_provider())
# Use it
print(await c.ai_prompt("Create a red cube at the origin"))
asyncio.run(main())
What the adapter does with those values — it builds the deployment-scoped
request and sends the key in the api-key header:
POST https://my-openai-resource.openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2024-06-01
api-key: YOUR_AZURE_API_KEY
{"model": "gpt-4o-mini", "messages": [...], "stream": false}
Notes:
You may omit base_url entirely (the placeholder
https://RESOURCE.openai.azure.com is filled in from extra.resource) or
pass the full base URL explicitly.
If you use an AI Foundry serverless model endpoint (the
*.services.ai.azure.com/models surface) instead of a deployment-scoped
resource, point provider at the generic OpenAI-compatible adapter with the
serverless base URL: provider="openai_compat",
base_url="https://<resource>.services.ai.azure.com/models".
The same configuration can be applied at startup instead of at runtime:
import asyncio
from blender_open_mcp.client.client import BlenderMCPClient
async def main():
async with BlenderMCPClient("http://localhost:8000") as c:
print(await c.get_scene_info())
await c.create_object("SPHERE", location=(0, 0, 2))
print(await c.ai_prompt("What should I build next?"))
asyncio.run(main())
Provider layer internals
src/blender_open_mcp/llm.py keeps a registry of provider specs and routes
every request through one chat helper:
OpenAI-style providers post to <base_url>/chat/completions with a
Bearer token when an API key is set, and parse
choices[0].message.content.
Ollama posts to /api/chat natively (or to its /v1/chat/completions
surface when the base URL ends in /v1).
Azure posts to
https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=…
using the api-key header.
Model listing: Ollama /api/tags, others /models (Azure deployments
are managed in the portal and not listed).
Add new backends by inserting an entry in PROVIDERS (plus an alias in
PROVIDER_ALIASES); nothing else changes.
Development
.venv/Scripts/python -m pytest tests -q
The suites mock bpy (addon tests), httpx (provider/PolyHaven routing),
and the MCP client wire format, so they run without Blender or a live LLM.
tests/test_integration.py additionally proves the layers work together:
an in-process fastmcp.Client session lists tools/prompts and calls
provider tools over the real MCP protocol;
the actual addon.py TCP server loop is started on a local port (bpy
mocked) and driven through the MCP server's Blender bridge, so
blender_get_scene_info and blender_execute_code round-trip over a real
socket;
a parity test pins every bridge command to a registered addon handler and
every blender_* tool to a registered MCP tool;
TestMainThreadDispatch in tests/test_addon.py covers the add-on's
main-thread marshalling: bpy handlers run on the timer pump rather than the
connection thread, errors propagate back to the caller, network-only commands
stay on the worker thread, and a stopped pump releases blocked workers.
Notes / known gaps
Tests exercise the server without a live Blender; run them against a real
Blender session to validate addon.py end to end.
Blender API calls are executed on Blender's main thread via a
bpy.app.timers pump, so scene commands are serialised: a long render or a
heavy blender_execute_code build delays whatever is queued behind it.
PolyHaven downloads and LLM calls stay on worker threads and don't block the
UI. If Blender is busy with a modal operator, commands wait rather than
running against an invalid context.
See ARCHITECTURE.md for the component diagram and AGENTS.md for
contributor conventions.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Blender Open?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Blender Open einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Blender Open?
Blender Open läuft lokal über stdio.
Wann wurde Blender Open zuletzt geprüft?
Zuletzt geprüft: 2026-11-05. MCP for Blender Using Open Weights Models