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

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

Point your MCP client at http://localhost:8000/mcp (streamable HTTP) or run blender-mcp --transport stdio.

Example Claude/Cursor-style config:

{
  "mcpServers": {
    "blender": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Available MCP tools

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.

PolyHaven assets:

... View full README on GitHub