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/blender_open_mcp/server.py	MCP server: Blender tools, PolyHaven tools, LLM prompt + provider tools
src/blender_open_mcp/llm.py	Provider-agnostic LLM layer (registry, adapters, model listing)
src/blender_open_mcp/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.

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:

blender-mcp                          # Ollama at http://localhost:11434, model llama3.2

Or pick a different backend at startup:

# 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 openai_compat --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 "$OPENAI_API_KEY" --llm-model gpt-4o-mini

# Azure AI Foundry / Azure OpenAI
blender-mcp --llm-provider azure --llm-api-key "$AZURE_API_KEY" \
            --llm-base-url https://my-resource.openai.azure.com \
            --llm-model my-deployment \
            --llm-extra '{"resource":"my-resource","deployment":"my-deployment","api_version":"2024-06-01"}'

Environment variables are honored: BLENDER_OPEN_MCP_PROVIDER, BLENDER_OPEN_MCP_BASE_URL, BLENDER_OPEN_MCP_MODEL, BLENDER_OPEN_MCP_API_KEY.

Other useful flags: --host, --port (MCP endpoint, default 0.0.0.0:8000), --blender-host, --blender-port, --transport streamable_http|http|stdio.

4. Register with an MCP client