blender-mcp

Blender .blend ファイルを構築する MCP サーバーです。Blender への接続方法は 2 通りあります。

• ヘッドレス — 呼び出しのたびに新しい blender --background プロセスを起動します。決定論的で、常に利用可能であり、ファイル生成に適した方法です。

• ライブ — 小さな Blender アドオンがローカルポートを開き、サーバーが既に開いている Blender ウィンドウを操作できるようにします。その様子をリアルタイムで確認できます。

どちらのルートも同じハンドラーコードを実行するため、スクリプトはどちらの方法でも同じように動作します。ローカルの Web UI を使用すると、参照画像をアップロードし、同じツールで生成ジョブを実行できます。

必要条件

Related MCP server: Blender MCP

セットアップ

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

.env を省略した場合、サーバーは PATH と各ドライブの標準的な Program Files/Blender Foundation/Blender <version> フォルダーを検索し、見つかった最新バージョンを優先します。

ライブブリッジを有効にする

アドオンはインストールされていますが、起動するまではアイドル状態です。

1. Blender を開きます。

2. 3D ビューポートで N を押してサイドバーを表示します。

3. MCP タブを開き、Start MCP Bridge をクリックします。

アドオンの設定で Start listening on launch にチェックを入れると、毎回この操作を省略できます。

MCP クライアントを接続する

.cursor/mcp.json には、このプロジェクト用のサーバーが既に登録されています。すべての場所で利用できるようにするには、そのブロックを ~/.cursor/mcp.json にコピーします。

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

品質ワークフロー

生成品質は、単一のスクリプトダンプではなく、確認によって向上します。

1. list_references / view_reference — 最初にガイド画像を開く

2. studio または product から create_blend

3. 小さな run_script ステップで構築；apply_material で金属/プラスチック/ゴム/ガラス/木材を適用

4. preview_views — マルチアングルの EEVEE プレビュー；view_image で参照と比較

5. 修正、再度プレビュー

6. 最終 render / render_and_view（最終版のみ CYCLES、反復中は EEVEE）

ローカル Web UI

uv run blender-mcp-web
# open http://127.0.0.1:8765

参照画像をアップロードし、プロンプトを入力し、output/jobs/ 以下のジョブを参照します。

• .env に BLENDER_MCP_LLM_API_KEY がある場合 — サイトは制限付きマルチモーダルエージェントを実行し、同じ Blender ツールを呼び出します（OpenAI 互換または BLENDER_MCP_LLM_PROVIDER による Anthropic）。

• キーがない場合 — アップロードとジョブページは引き続き機能します。Cursor でジョブを開き、MCP エージェントに output/jobs/<id>/refs から構築するよう依頼します。

ツール

スクリプトの作成

run_script および create_blend の script 引数は、bpy、mathutils、math、D（bpy.data）、C（bpy.context）が既にバインドされた名前空間で実行されます。result に代入するか emit(value) を呼び出すことでデータを返します。

テンプレート

レイアウト

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

テスト

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

注意事項と制限

• run_script は Blender 内で任意の Python を実行します。ブリッジはループバックに限定してください。

• 長時間のレンダリングは、完了するまでライブ UI をブロックします。

• viewport_screenshot はライブモードのみです。

• Cycles は、Blender の設定で GPU デバイスを有効にしない限り CPU を使用します。

• Web エージェントには、ツール呼び出しと画像をサポートするマルチモーダルモデルが必要です。

ライセンス

MIT