Skip to content
Back to search

blender-open-mcp

MCP for Blender Using Open Weights Models

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dhakalnirajan--blender-open-mcp/badge.svg)](/listings/dhakalnirajan--blender-open-mcp)

HTML

<a href="/listings/dhakalnirajan--blender-open-mcp"><img src="/api/listings/dhakalnirajan--blender-open-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Blender Open MCP
  2. Local-first **Model Context Protocol (MCP)** server for controlling a live
  3. Blender session from AI agents, with a **provider-agnostic LLM backend**:
  4. - **Ollama**
  5. - **LM Studio**
  6. - **llama.cpp** server
  7. - **OpenAI** (and every OpenAI-compatible endpoint: vLLM, TGI, OpenRouter,
  8. Groq, Together, Azure AI Foundry via its OpenAI-compatible surface, …)
  9. - any server that speaks `POST /chat/completions` with an optional base URL
  10. and API key
  11. Providers are configured at startup (CLI flags or environment variables) and
  12. can be **switched at runtime** through MCP tools, so an agent can hop between
  13. backends without restarting the server.
  14. ```
  15. MCP Client ──▶ FastMCP Server ──▶ (TCP 9876) ──▶ Blender add-on (addon.py) ──▶ bpy
  16. │
  17. └──────────────▶ (HTTP) ──▶ LLM provider (Ollama / LM Studio /
  18. llama.cpp / OpenAI-compatible / Azure)
  19. ```
  20. ---
  21. ## Repository layout
  22. | Path | Purpose |
  23. | --- | --- |
  24. | `addon.py` | Single-file Blender add-on: TCP server + scene/render/PolyHaven handlers + sidebar panel |
  25. | `src/blender_open_mcp/server.py` | MCP server: Blender tools, PolyHaven tools, LLM prompt + provider tools |
  26. | `src/blender_open_mcp/llm.py` | Provider-agnostic LLM layer (registry, adapters, model listing) |
  27. | `src/blender_open_mcp/client/` | Canonical async MCP client + CLI |
  28. | `client/` | Thin compat wrapper so `from client import …` keeps working from source |
  29. | `tests/` | pytest suites (server, client, addon) |
  30. ---
  31. ## Quick start
  32. ### 1. Install
  33. Requires Python ≥ 3.10.
  34. ```bash
  35. python -m venv .venv
  36. .venv/Scripts/pip install -e ".[dev]" # Windows (bash/PowerShell)
  37. # or: source .venv/bin/activate && pip install -e ".[dev]" # macOS/Linux
  38. ```
  39. ### 2. Enable the Blender add-on
  40. 1. Open Blender.
  41. 2. `Edit → Preferences → Add-ons → Install…`, choose `addon.py`.
  42. 3. Enable **Blender MCP**.
  43. 4. In the 3D Viewport press `N`, open the **Blender MCP** tab and click
  44. **Start MCP Server** (listens on `localhost:9876` by default).
  45. ### 3. Start the MCP server
  46. Default LLM backend is Ollama:
  47. ```bash
  48. blender-mcp # Ollama at http://localhost:11434, model llama3.2
  49. ```
  50. Or pick a different backend at startup:
  51. ```bash
  52. # LM Studio (OpenAI-compatible, default localhost:1234/v1)
  53. blender-mcp --llm-provider lmstudio --llm-model "local-model"
  54. # llama.cpp server (default localhost:8080/v1)
  55. blender-mcp --llm-provider llamacpp --llm-model qwen2.5-coder
  56. # OpenAI-compatible generic endpoint
  57. blender-mcp --llm-provider openai_compat --llm-base-url http://my-server:8000/v1 \
  58. --llm-api-key sk-... --llm-model my-model
  59. # OpenAI
  60. blender-mcp --llm-provider openai --llm-api-key "$OPENAI_API_KEY" --llm-model gpt-4o-mini
  61. # Azure AI Foundry / Azure OpenAI
  62. blender-mcp --llm-provider azure --llm-api-key "$AZURE_API_KEY" \
  63. --llm-base-url https://my-resource.openai.azure.com \
  64. --llm-model my-deployment \
  65. --llm-extra '{"resource":"my-resource","deployment":"my-deployment","api_version":"2024-06-01"}'
  66. ```
  67. Environment variables are honored: `BLENDER_OPEN_MCP_PROVIDER`,
  68. `BLENDER_OPEN_MCP_BASE_URL`, `BLENDER_OPEN_MCP_MODEL`,
  69. `BLENDER_OPEN_MCP_API_KEY`.
  70. Other useful flags: `--host`, `--port` (MCP endpoint, default `0.0.0.0:8000`),
  71. `--blender-host`, `--blender-port`, `--transport streamable_http|http|stdio`.
  72. ### 4. Register with an MCP client
  73. Point your MCP client at `http://localhost:8000/mcp` (streamable HTTP) or run
  74. `blender-mcp --transport stdio`.
  75. Example Claude/Cursor-style config:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "blender": {
  80. "url": "http://localhost:8000/mcp"
  81. }
  82. }
  83. }
  84. ```
  85. ---
  86. ## Available MCP tools
  87. **Scene / object control** (forwarded to the Blender add-on over TCP):
  88. `blender_get_scene_info`, `blender_get_object_info`, `blender_create_object`,
  89. `blender_modify_object`, `blender_delete_object`, `blender_set_material`,
  90. `blender_render_image`, `blender_execute_code`.
  91. **PolyHaven assets:** `blender_get_polyhaven_categories`,
  92. `blender_search_polyhaven_assets`, `blender_download_polyhaven_asset`,
  93. `blender_set_texture`.
  94. **LLM / provider control:**
  95. - `blender_ai_prompt` – send a prompt to the active backend (per-call
  96. `provider`/`base_url`/`model`/`api_key` overrides supported).
  97. - `blender_get_llm_provider` – show active provider config (API key masked).
  98. - `blender_set_llm_provider` – switch/configure the backend at runtime.
  99. - `blender_list_llm_models` – list models (Ollama `/api/tags` or
  100. OpenAI-compatible `/models`).
  101. **Legacy aliases:** `blender_set_ollama_model`, `blender_set_ollama_url`,
  102. `blender_get_ollama_models` keep old Ollama-only clients working.
  103. **MCP Prompts** (`prompts/list` / `prompts/get`):
  104. - `blender_build_scene` – guided plan for building a scene from a description.
  105. - `blender_review_scene` – read-only inspection workflow.
  106. - `blender_configure_llm` – provider-switching instructions with examples.
  107. Prompts are registered in `src/blender_open_mcp/prompts.py`.
  108. ### Runtime provider switching (examples)
  109. ```text
  110. # Switch to LM Studio
  111. tool blender_set_llm_provider {"provider":"lmstudio","base_url":"http://localhost:1234/v1","model":"local-model"}
  112. # Switch to llama.cpp
  113. tool blender_set_llm_provider {"provider":"llamacpp","base_url":"http://localhost:8080/v1"}
  114. # Back to Ollama
  115. tool blender_set_llm_provider {"provider":"ollama","base_url":"http://localhost:11434","model":"llama3.2"}
  116. ```
  117. #### Azure AI Foundry (worked example)
  118. Azure's OpenAI-compatible endpoint is deployment-scoped, so three values from
  119. your Azure AI Foundry project are required — all of them go into the `extra`
  120. parameter, and the model you name in `model` must match the deployment name:
  121. 1. **Resource name** — in the Azure portal, open your resource (e.g.
  122. *Azure OpenAI* or *AI Foundry project*) and take the short name from its
  123. endpoint URL: `https://<resource>.openai.azure.com/...`.
  124. 2. **Deployment name** — on the *Deployments* page, e.g. `gpt-4o-mini`.
  125. This is what you pass as `model` (it is *not* the base model name).
  126. 3. **API key** — on the resource's *Keys and Endpoint* page.
  127. 4. **API version** (optional) — e.g. `2024-06-01` (the adapter defaults to it).
  128. Switch to Azure at runtime with a single call (CLI form):
  129. ```bash
  130. blender-mcp-client --host http://localhost:8000 tool blender_set_llm_provider \
  131. '{"provider":"azure","api_key":"YOUR_AZURE_API_KEY","model":"gpt-4o-mini",' \
  132. '"extra":{"resource":"my-openai-resource","deployment":"gpt-4o-mini","api_version":"2024-06-01"}}'
  133. ```
  134. The same call through the Python API:
  135. ```python
  136. import asyncio
  137. from blender_open_mcp.client.client import BlenderMCPClient
  138. async def main():
  139. async with BlenderMCPClient("http://localhost:8000") as c:
  140. # Switch to Azure AI Foundry
  141. print(await c.set_llm_provider(
  142. provider="azure",
  143. api_key="YOUR_AZURE_API_KEY",
  144. model="gpt-4o-mini",
  145. extra={
  146. "resource": "my-openai-resource",
  147. "deployment": "gpt-4o-mini",
  148. "api_version": "2024-06-01",
  149. },
  150. ))
  151. # Confirm the active config (API key is masked)
  152. print(await c.get_llm_provider())
  153. # Use it
  154. print(await c.ai_prompt("Create a red cube at the origin"))
  155. asyncio.run(main())
  156. ```
  157. What the adapter does with those values — it builds the deployment-scoped
  158. request and sends the key in the `api-key` header:
  159. ```
  160. POST https://my-openai-resource.openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2024-06-01
  161. api-key: YOUR_AZURE_API_KEY
  162. {"model": "gpt-4o-mini", "messages": [...], "stream": false}
  163. ```
  164. Notes:
  165. - You may omit `base_url` entirely (the placeholder
  166. `https://RESOURCE.openai.azure.com` is filled in from `extra.resource`) or
  167. pass the full base URL explicitly.
  168. - If you use an AI Foundry **serverless model endpoint** (the
  169. `*.services.ai.azure.com/models` surface) instead of a deployment-scoped
  170. resource, point `provider` at the generic OpenAI-compatible adapter with the
  171. serverless base URL: `provider="openai_compat"`,
  172. `base_url="https://<resource>.services.ai.azure.com/models"`.
  173. - The same configuration can be applied at startup instead of at runtime:
  174. ```bash
  175. blender-mcp --llm-provider azure \
  176. --llm-api-key "$AZURE_API_KEY" \
  177. --llm-model gpt-4o-mini \
  178. --llm-extra '{"resource":"my-openai-resource","deployment":"gpt-4o-mini","api_version":"2024-06-01"}'
  179. ```
  180. ```
  181. ---
  182. ## Client CLI
  183. ```bash
  184. blender-mcp-client --host http://localhost:8000 tools
  185. blender-mcp-client --host http://localhost:8000 tool blender_get_scene_info
  186. blender-mcp-client --host http://localhost:8000 tool blender_set_llm_provider '{"provider":"lmstudio"}'
  187. blender-mcp-client --host http://localhost:8000 prompt "Create a metallic sphere at 0,0,2"
  188. blender-mcp-client --host http://localhost:8000 interactive
  189. ```
  190. As a library:
  191. ```python
  192. import asyncio
  193. from blender_open_mcp.client.client import BlenderMCPClient
  194. async def main():
  195. async with BlenderMCPClient("http://localhost:8000") as c:
  196. print(await c.get_scene_info())
  197. await c.create_object("SPHERE", location=(0, 0, 2))
  198. print(await c.ai_prompt("What should I build next?"))
  199. asyncio.run(main())
  200. ```
  201. ---
  202. ## Provider layer internals
  203. `src/blender_open_mcp/llm.py` keeps a registry of provider specs and routes
  204. every request through one chat helper:
  205. - **OpenAI-style** providers post to `<base_url>/chat/completions` with a
  206. `Bearer` token when an API key is set, and parse
  207. `choices[0].message.content`.
  208. - **Ollama** posts to `/api/chat` natively (or to its `/v1/chat/completions`
  209. surface when the base URL ends in `/v1`).
  210. - **Azure** posts to
  211. `https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=…`
  212. using the `api-key` header.
  213. - **Model listing**: Ollama `/api/tags`, others `/models` (Azure deployments
  214. are managed in the portal and not listed).
  215. Add new backends by inserting an entry in `PROVIDERS` (plus an alias in
  216. `PROVIDER_ALIASES`); nothing else changes.
  217. ---
  218. ## Development
  219. ```bash
  220. .venv/Scripts/python -m pytest tests -q
  221. ```
  222. The suites mock `bpy` (addon tests), `httpx` (provider/PolyHaven routing),
  223. and the MCP client wire format, so they run without Blender or a live LLM.
  224. `tests/test_integration.py` additionally proves the layers work together:
  225. - an in-process `fastmcp.Client` session lists tools/prompts and calls
  226. provider tools over the real MCP protocol;
  227. - the actual `addon.py` TCP server loop is started on a local port (bpy
  228. mocked) and driven through the MCP server's Blender bridge, so
  229. `blender_get_scene_info` and `blender_execute_code` round-trip over a real
  230. socket;
  231. - a parity test pins every bridge command to a registered addon handler and
  232. every `blender_*` tool to a registered MCP tool;
  233. - `TestMainThreadDispatch` in `tests/test_addon.py` covers the add-on's
  234. main-thread marshalling: bpy handlers run on the timer pump rather than the
  235. connection thread, errors propagate back to the caller, network-only commands
  236. stay on the worker thread, and a stopped pump releases blocked workers.
  237. ## Notes / known gaps
  238. - Tests exercise the server without a live Blender; run them against a real
  239. Blender session to validate `addon.py` end to end.
  240. - Blender API calls are executed on Blender's main thread via a
  241. `bpy.app.timers` pump, so scene commands are serialised: a long render or a
  242. heavy `blender_execute_code` build delays whatever is queued behind it.
  243. PolyHaven downloads and LLM calls stay on worker threads and don't block the
  244. UI. If Blender is busy with a modal operator, commands wait rather than
  245. running against an invalid context.
  246. - See `ARCHITECTURE.md` for the component diagram and `AGENTS.md` for
  247. contributor conventions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.