blender-open-mcp

Blender Open MCP

以本地优先的 Model Context Protocol (MCP) 服务，可通过 AI Agent 控制正在运行的 Blender 会话，并支持与提供方无关的大模型后端：

• Ollama
• LM Studio
• llama.cpp 服务
• OpenAI（以及所有兼容 OpenAI 的端点：vLLM、TGI、OpenRouter、 Groq、Together、通过兼容 OpenAI 的接口提供服务的 Azure AI Foundry，……）
• 任何支持 POST /chat/completions 的服务，可选配置基础 URL 和 API 密钥

提供方在启动时配置（通过 CLI 标志或环境变量），也可以通过 MCP 工具在运行时切换，因此 Agent 可以在不同后端之间切换，无需重启服务。

MCP Client ──▶ FastMCP Server ──▶ (TCP 9876) ──▶ Blender add-on (addon.py) ──▶ bpy
                  │
                  └──────────────▶ (HTTP) ──▶ LLM provider (Ollama / LM Studio /
                                               llama.cpp / OpenAI-compatible / Azure)

---

仓库布局

路径	用途
addon.py	单文件 Blender 插件：TCP 服务 + 场景/渲染/PolyHaven 处理程序 + 侧边栏面板
src/blender_open_mcp/server.py	MCP 服务：Blender 工具、PolyHaven 工具、大模型提示词与提供方工具
src/blender_open_mcp/llm.py	与提供方无关的大模型层（注册表、适配器、模型列表）
src/blender_open_mcp/client/	标准异步 MCP 客户端 + CLI
client/	轻量兼容包装器，确保从源码使用 from client import … 仍可正常工作
tests/	pytest 测试套件（服务端、客户端、插件）

---

快速开始

1. 安装

需要 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. 启用 Blender 插件

1. 打开 Blender。
2. Edit → Preferences → Add-ons → Install…，选择 addon.py。
3. 启用 Blender MCP。
4. 在 3D 视口中按 N，打开 Blender MCP 选项卡并点击 Start MCP Server（默认监听 localhost:9876）。

3. 启动 MCP 服务

默认的大模型后端是 Ollama：

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

也可以在启动时选择其他后端：

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

支持以下环境变量：BLENDER_OPEN_MCP_PROVIDER、 BLENDER_OPEN_MCP_BASE_URL、BLENDER_OPEN_MCP_MODEL、 BLENDER_OPEN_MCP_API_KEY。

其他实用标志：--host、--port（MCP 端点，默认为 0.0.0.0:8000）、 --blender-host、--blender-port、--transport streamable_http|http|stdio。

4. 注册到 MCP 客户端

将 MCP 客户端指向 http://localhost:8000/mcp（streamable HTTP），或运行 blender-mcp --transport stdio。

Claude/Cursor 风格的配置示例：

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

---

可用的 MCP 工具

场景 / 对象控制（通过 TCP 转发到 Blender 插件）： 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 资源： blender_get_polyhaven_categories、 blender_search_polyhaven_assets、blender_download_polyhaven_asset、 blender_set_texture。

大模型 / 提供方控制：

• blender_ai_prompt – 向当前后端发送提示词（支持按调用覆盖 provider/base_url/model/api_key）。
• blender_get_llm_provider – 显示当前提供方配置（API 密钥会隐藏）。
• blender_set_llm_provider – 在运行时切换/配置后端。
• blender_list_llm_models – 列出模型（Ollama /api/tags 或 兼容 OpenAI 的 /models）。

旧版别名： blender_set_ollama_model、blender_set_ollama_url、 blender_get_ollama_models 可继续用于旧版 Ollama 专用客户端。

MCP 提示词（prompts/list / prompts/get）：

• blender_build_scene – 根据描述引导制定场景搭建计划。
• blender_review_scene – 只读检查工作流。
• blender_configure_llm – 提供切换提供方的说明和示例。

提示词注册在 src/blender_open_mcp/prompts.py 中。

运行时切换提供方（示例）

# 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（示例）

Azure 的 OpenAI 兼容端点按部署范围限定，因此需要 Azure AI Foundry 项目中的三个值——它们都要填入 extra 参数，并且 model 中指定的模型必须与部署名称一致：

1. 资源名称——在 Azure 门户中打开你的资源（例如 Azure OpenAI 或 AI Foundry project），从其端点 URL 中获取简短名称：https://<resource>.openai.azure.com/...。
2. 部署名称——在 Deployments 页面中查看，例如 gpt-4o-mini。这就是要传入 model 的值（并非基础模型名称）。
3. API 密钥——在资源的 Keys and Endpoint 页面中查看。
4. API 版本（可选）——例如 2024-06-01（适配器默认使用此版本）。

在运行时只需调用一次即可切换到 Azure（CLI 形式）：

blender-mcp-client --host http://localhost:8000 tool blender_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"}}'

通过 Python API 调用相同配置：

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())

适配器如何使用这些值——它会构建按部署范围限定的请求，并在 api-key 标头中发送密钥：

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}

注意：

• 可以完全省略 base_url（占位符 https://RESOURCE.openai.azure.com 会根据 extra.resource 填充），也可以显式传入完整的基础 URL。
• 如果使用的是 AI Foundry 无服务器模型端点（*.services.ai.azure.com/models 这一端点），而不是按部署范围限定的资源，请将 provider 指向通用的 OpenAI 兼容适配器，并使用无服务器基础 URL：provider="openai_compat"、 base_url="https://<resource>.services.ai.azure.com/models"。
• 相同配置也可以在启动时应用，而不是在运行时应用：

blender-mcp --llm-provider azure \
  --llm-api-key "$AZURE_API_KEY" \
  --llm-model gpt-4o-mini \
  --llm-extra '{"resource":"my-openai-resource","deployment":"gpt-4o-mini","api_version":"2024-06-01"}'

---

## Client CLI

```bash
blender-mcp-client --host http://localhost:8000 tools
blender-mcp-client --host http://localhost:8000 tool blender_get_scene_info
blender-mcp-client --host http://localhost:8000 tool blender_set_llm_provider '{"provider":"lmstudio"}'
blender-mcp-client --host http://localhost:8000 prompt "Create a metallic sphere at 0,0,2"
blender-mcp-client --host http://localhost:8000 interactive

作为库使用：

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())

---

提供商层内部机制

src/blender_open_mcp/llm.py 会维护提供商规范注册表，并通过一个聊天辅助函数路由所有请求：

• OpenAI 风格提供商会向 <base_url>/chat/completions 发送请求；设置了 API 密钥时，会使用 Bearer 令牌，并解析 choices[0].message.content。
• Ollama 原生向 /api/chat 发送请求（如果基础 URL 以 /v1 结尾，则使用其 /v1/chat/completions 端点）。
• Azure 会向 https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=… 发送请求，并使用 api-key 标头。
• 模型列表：Ollama 使用 /api/tags，其他提供商使用 /models（Azure 部署在门户中管理，不会列出）。

添加新的后端时，只需在 PROVIDERS 中添加一项（并在 PROVIDER_ALIASES 中添加一个别名）；无需更改其他内容。

---

开发

.venv/Scripts/python -m pytest tests -q

测试套件会模拟 bpy（插件测试）、httpx（提供商／PolyHaven 路由） 和 MCP 客户端线路格式，因此无需 Blender 或实际运行的大模型即可执行。

tests/test_integration.py 还会验证各层协同工作：

• 进程内的 fastmcp.Client 会话会列出工具／提示词，并通过实际 MCP 协议调用提供商工具；
• 实际的 addon.py TCP 服务循环会在本地端口启动（模拟 bpy），并通过 MCP 服务的 Blender 桥接进行驱动，因此 blender_get_scene_info 和 blender_execute_code 会通过实际套接字完成往返通信；
• 一项一致性测试会将每个桥接命令与已注册的插件处理程序对应，并将每个 blender_* 工具与已注册的 MCP 工具对应；
• tests/test_addon.py 中的 TestMainThreadDispatch 会覆盖插件的主线程调度：bpy 处理程序在定时器循环中运行，而不是在连接线程中运行；错误会传回调用方；仅限网络的命令会留在工作线程中；停止循环后会释放被阻塞的工作线程。

备注 / 已知不足

• 测试在没有运行中的 Blender 的情况下测试服务；请在真实的 Blender 会话中运行测试，以端到端验证 addon.py。
• Blender API 调用通过 bpy.app.timers 泵在 Blender 主线程上执行，因此场景命令会串行处理：耗时较长的渲染或繁重的 blender_execute_code 构建会延迟排在其后的任务。PolyHaven 下载和 LLM 调用会在工作线程中执行，不会阻塞 UI。如果 Blender 正在执行模态操作器，命令会等待，而不会在无效上下文中运行。
• 组件图见 ARCHITECTURE.md，贡献者规范见 AGENTS.md。