dhakalnirajan/blender-open-mcp

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, …)
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.
MCP Client ──▶ FastMCP Server ──▶ (TCP 9876) ──▶ Blender add-on (addon.py) ──▶ bpy
└──────────────▶ (HTTP) ──▶ LLM provider (Ollama / LM Studio /
llama.cpp / OpenAI-compatible / Azure)
## Repository layout
| Path | Purpose |
| addon.py | Single-file Blender add-on: TCP server + scene/render/PolyHaven handlers + sidebar panel |
| src/blenderopenmcp/server.py | MCP server: Blender tools, PolyHaven tools, LLM prompt + provider tools |
| src/blenderopenmcp/llm.py | Provider-agnostic LLM layer (registry, adapters, model listing) |
| src/blenderopenmcp/client/ | Canonical async MCP client + CLI |
| client/ | Thin compat wrapper so from client import … keeps working from source |
| tests/ | pytest suites (server, client, addon) |
## Quick start
### 1. Install
Requires Python ≥ 3.10.
bash
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]" # Windows (bash/PowerShell)
# or: source .venv/bin/activate && pip install -e ".[dev]" # macOS/Linux
### 2. Enable the Blender add-on
1. Open Blender.
2. Edit → Preferences → Add-ons → Install…, choose addon.py.
3. Enable Blender MCP.
4. In the 3D Viewport press N, open the Blender MCP tab and click
Start MCP Server (listens on localhost:9876 by default).
### 3. Start the MCP server
Default LLM backend is Ollama:
bash
blender-mcp # Ollama at http://localhost:11434, model llama3.2
Or pick a different backend at startup:
bash
# LM Studio (OpenAI-compatible, default localhost:1234/v1)
blender-mcp --llm-provider lmstudio --llm-model "local-model"
# llama.cpp server (default localhost:8080/v1)
blender-mcp --llm-provider llamacpp --llm-model qwen2.5-coder
# OpenAI-compatible generic endpoint
blender-mcp --llm-provider openaicompat --llm-base-url http://my-server:8000/v1 \
--llm-api-key sk-... --llm-model my-model
# OpenAI
blender-mcp --llm-provider openai --llm-api-key "$OPENAIAPIKEY" --llm-model gpt-4o-mini
# Azure AI Foundry / Azure OpenAI
blender-mcp --llm-provider azure --llm-api-key "$AZUREAPIKEY" \
--llm-base-url https://my-resource.openai.azure.com \
--llm-model my-deployment \
--llm-extra '{"resource":"my-resource","deployment":"my-deployment","apiversion":"2024-06-01"}'
Environment variables are honored: BLENDEROPENMCPPROVIDER,
BLENDEROPENMCPBASEURL, BLENDEROPENMCPMODEL,
BLENDEROPENMCPAPIKEY.
Other useful flags: --host, --port (MCP endpoint, default 0.0.0.0:8000),
--blender-host, --blender-port, --transport streamablehttp|http|stdio.
### 4. Register with an MCP client
Point your MCP client at http://localhost:8000/mcp (streamable HTTP) or run
blender-mcp --transport stdio.
Example Claude/Cursor-style config:
json