blender-open-mcp

Blender Open MCP

AI エージェントから実行中の Blender セッションを制御する、ローカルファーストなModel Context Protocol（MCP）サーバーです。プロバイダーに依存しない LLM バックエンドを備えています。

• Ollama
• LM Studio
• llama.cpp サーバー
• OpenAI（および、vLLM、TGI、OpenRouter、Groq、Together、OpenAI 互換のインターフェース経由の Azure AI Foundry など、OpenAI 互換エンドポイントすべて）
• オプションのベース URL と API キーを指定して POST /chat/completions に対応するサーバー

プロバイダーは起動時に（CLI フラグまたは環境変数で）設定し、MCP ツールから実行時に切り替えることもできます。そのため、サーバーを再起動せずに、エージェントはバックエンドを切り替えられます。

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 ツール、LLM プロンプトとプロバイダーツール
src/blender_open_mcp/llm.py	プロバイダーに依存しない LLM レイヤー（レジストリ、アダプター、モデル一覧）
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 サーバーを起動する

デフォルトの LLM バックエンドは 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（ストリーム可能な 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。

LLM／プロバイダー制御：

• 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 プロジェクトから 3 つの値が必要です。すべて 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（アダプターのデフォルト値です）。

1 回の呼び出しで実行時に 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 のエンドポイント）を使用する場合は、サーバーレスのベース URL を指定して、provider に汎用の OpenAI 互換アダプターを設定します：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 はプロバイダー仕様のレジストリを保持し、すべてのリクエストを 1 つのチャットヘルパー経由でルーティングします。

• OpenAI 形式のプロバイダーは、API キーが設定されている場合は Bearer トークンを使い、<base_url>/chat/completions に POST して、choices[0].message.content を解析します。
• Ollama は標準で /api/chat に POST します（ベース URL が /v1 で終わる場合は、/v1/chat/completions のエンドポイントに POST します）。
• Azure は api-key ヘッダーを使い、https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=… に POST します。
• モデル一覧の取得：Ollama は /api/tags、その他は /models を使用します（Azure のデプロイメントはポータルで管理されており、一覧には表示されません）。

新しいバックエンドを追加するには、PROVIDERS にエントリーを追加し（さらに PROVIDER_ALIASES にエイリアスを追加します）。それ以外の変更は不要です。

---

開発

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

テストスイートでは bpy（アドオンのテスト）、httpx（プロバイダー／PolyHaven のルーティング）、MCP クライアントのワイヤーフォーマットをモックするため、Blender や稼働中の LLM がなくても実行できます。

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 を起動せずにサーバーをテストします。addon.py のエンドツーエンドの動作を検証するには、実際の Blender セッションに対してテストを実行してください。
• Blender API の呼び出しは、bpy.app.timers のポンプを介して Blender のメインスレッドで実行されるため、シーンコマンドは直列化されます。時間のかかるレンダリングや負荷の高い blender_execute_code のビルドがあると、その後にキューに追加された処理が遅延します。PolyHaven のダウンロードと LLM の呼び出しはワーカースレッドで実行され、UI をブロックしません。Blender がモーダルオペレーターでビジー状態の場合、無効なコンテキストでコマンドを実行せず、待機します。
• コンポーネント図については ARCHITECTURE.md を、コントリビューター向けの規約については AGENTS.md を参照してください。