three.ws Blender

@three-ws/blender-mcp

お使いのマシンにある Blender を、あらゆる AI エージェントで利用できます。ヘッドレスで、GUI もアドオンのインストールも不要です。

---

Model Context Protocol サーバーです。stdio 経由で AI アシスタントに実際の Blender を提供します。3D ファイルの検査、GLB、glTF、FBX、OBJ、STL、PLY、Collada、Alembic、USD、.blend 間の変換、オートフレーム・オートライティングされたプレビューのレンダリング（アシスタントが確認できるよう インライン で返されます）、シーンに対する bpy スクリプトの実行、無料の three.ws Forge レーンでのテキストプロンプトからのモデル生成が可能です。

Blender はバックグラウンドモード（blender -b）で実行され、呼び出しごとに 1 つのプロセスが起動します。そのため、サーバーや CI、コンテナ内でも動作し、ディスプレイや維持が必要な GUI セッション、Blender への事前のアドオンインストールは不要です。すべて実際の環境で動作します。各ツールはマシンにインストールされた Blender を操作し、blender_forge_import は稼働中の公開 three.ws 生成パイプラインを呼び出します。

要件

• Node.js 20 以降
• Blender 3.0 以降（ローカルにインストール）。ダウンロードするか、パッケージマネージャーからインストールしてください。PATH にない場合は、BLENDER_PATH に実行ファイルのパスを設定します（macOS の場合は /Applications/Blender.app/Contents/MacOS/Blender）。

問題が発生した場合は、まず blender_info を呼び出してください。実行ファイル、バージョン、レンダーエンジン、このビルドでサポートされるファイル形式が正確に報告されます。

インストール

npm install @three-ws/blender-mcp

または、npx で実行できます（インストール不要）。

npx -y @three-ws/blender-mcp

Claude Code

claude mcp add blender -- npx -y @three-ws/blender-mcp

Claude Desktop / Cursor

これを MCP 設定に貼り付けてください（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）。

{
	"mcpServers": {
		"blender": {
			"command": "npx",
			"args": ["-y", "@three-ws/blender-mcp"]
		}
	}
}

Blender が PATH にない場合は、"env": { "BLENDER_PATH": "/path/to/blender" } を追加してください。

ツール

ツール	機能
blender_info	操作対象の Blender に関する情報（パス、バージョン、同梱 Python、使用可能なレンダーエンジン、このビルドが実際に対応しているインポート／エクスポート形式）を報告します。読み取り専用です。
blender_scene_info	3D ファイルを開いて、その内容を説明します。オブジェクトのタイプ、親、寸法、モディファイア、評価後の三角形数と頂点数、マテリアル、各画像の解像度とバイト数を含むテクスチャ一覧、アーマチュアのボーン名、フレーム範囲付きのアニメーションアクション、ワールド空間の境界を報告します。読み取り専用です。
blender_convert	ファイル拡張子に基づいて形式を選び、インポートして別の形式でエクスポートします。デフォルトではモディファイアを適用し、均一な単位スケールをベイクできます。対応形式の一覧はビルドによって異なります（Linux パッケージの中には USD、Collada、Alembic を含まないものがあります）。実際に対応している形式は blender_info が報告します。
blender_optimize	1 回の呼び出しで納品用の処理を行います。三角形数を上限に合わせて削減し、大きすぎるテクスチャを縮小し、参照されていないデータブロックを削除して、meshopt または Draco でメッシュストリームを圧縮します。処理前後の三角形数、テクスチャのバイト数、ファイルサイズを報告します。
blender_render	静止画の PNG をレンダリングし、インラインで返すため、ファイルシステムにアクセスできなくても、1 回の呼び出しでアシスタントが実際にモデルを確認できます。複数の視点を指定すると、1 回の起動でモデルを旋回させ、各角度を表示します。ファイルにカメラがない場合は、モデルの境界球に合わせたカメラを作成します。ライトがない場合は、キーライトと照明されたワールドを追加します。シーンにカメラと照明がすでにある場合は、作成時の設定でレンダリングします。
blender_run_python	シーンに対して bpy スクリプトを実行します。必要に応じて、最初にファイルを開き、実行後に結果をエクスポートできます。他のツールで対応できない処理に使うための手段です。
blender_forge_import	公開されている three.ws Forge パイプラインで、テキストプロンプトまたは参照画像からモデルを生成し、Blender に取り込みます。出力が別の形式を指定している場合は、取り込み時に変換します。デフォルトのレーンは無料です。

例

ファイルを変更する前に内容を確認する：

> What is in ~/assets/character.fbx?

blender_scene_info { "input": "~/assets/character.fbx" }
→ 4 meshes, 41,208 triangles, 1 armature (67 bones), 3 actions, bounds 1.78m tall

モデルを納品可能な状態にし、処理にかかった量を確認する：

blender_optimize { "input": "character.glb", "output": "character-web.glb", "max_triangles": 30000, "max_texture_px": 1024 }
→ 4.1 MB to 780 KB (81% saved): 96,412 to 30,000 triangles, textures 2048 to 1024, meshopt compressed

4 方向から同時に確認する：

blender_render { "input": "character-web.glb", "views": 4 }

クライアントの FBX をメートル単位の Web 対応 GLB に変換する：

blender_convert { "input": "character.fbx", "output": "character.glb", "scale": 0.01 }

作成したばかりのモデルを確認する：

blender_render { "input": "character.glb", "output": "preview.png", "samples": 64 }

1 回の呼び出しで三角形数を半分にしてエクスポートする：

blender_run_python {
  "input": "character.glb",
  "output": "character-lod1.glb",
  "code": "import bpy\nfor obj in bpy.data.objects:\n    if obj.type == 'MESH':\n        obj.modifiers.new('Decimate', 'DECIMATE').ratio = 0.5\nresult = {'meshes': len([o for o in bpy.data.objects if o.type == 'MESH'])}"
}

アセットを生成し、.blend として開く：

blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }

または、参照画像から再構築する：

blender_forge_import { "image": "./reference.png", "prompt": "a brass diving helmet", "output": "helmet.glb" }

圧縮 glTF

Meshopt および Draco で圧縮されたアセットは、外部バイナリをインストールすることなく、Blender が開く前にプロセス内で自動的にデコードされます。

これは単なる便利機能ではありません。Blender の glTF インポーターには EXT_meshopt_compression のデコーダーがありません。この拡張機能は gltfpack が出力し、多くの three.ws アバターの納品に使われています。この拡張機能を含むファイルを渡すと、"Extension EXT_meshopt_compression is not available on this addon version" というエラーが発生し、処理に失敗します。Draco は名目上はサポートされていますが、libextern_draco が含まれるビルドでのみ利用できます。一部の Linux ディストリビューションのパッケージには含まれていません。input を受け取るすべてのツールは同じデコード処理を行い、レスポンスの decoded_compression にデコードした内容を記載します。ファイルが変更されることはありません。デコードしたコピーはジョブの一時ディレクトリに置かれ、ジョブとともに削除されます。

呼び出しの仕組み

ツールを呼び出すたびに blender -b --factory-startup --python src/py/runner.py -- <job.json> <result.json> が起動し、終了します。知っておくべき点は次の3つです。

• --factory-startup により、保存済みの設定やサードパーティ製アドオンが結果に影響しないため、どのマシンでも同じファイルに変換できます。
• ランナーはペイロードをファイルに書き込み、標準出力には書き込みません。 Blender は進行状況、アドオンの出力、レンダリング統計を標準出力に表示するため、そのストリームからペイロードを見つけるのは当てずっぽうになります。そのため、結果ファイルがない場合は Blender が異常終了したことを意味し、エラーには理由を示すログ末尾が含まれます。
• 呼び出しごとに1プロセスです。 ジョブがクラッシュしても次のジョブには影響せず、呼び出しの間にプロセスが常駐することもありません。

失敗は構造化されたツールエラー（input_not_found、format_unsupported、engine_unavailable、timeout、blender_not_found、blender_unusable、blender_crashed）として返され、それぞれのメッセージに対処方法が示されます。blender_not_found は候補が見つからなかったことを意味し、blender_unusable は候補は見つかったものの実行できなかったことを意味します。後者には候補ごとの診断情報が含まれます。負荷の高いマシンではプローブの失敗が一時的なことがあり、すでにインストール済みのソフトウェアをインストールするよう案内するのは適切ではないためです。

環境変数

変数	デフォルト	用途
BLENDER_PATH	PATH およびプラットフォーム標準のインストール場所から検出	Blender 実行ファイルの絶対パスです。
BLENDER_MCP_TIMEOUT_MS	300000	1つの Blender ジョブに対する上限時間です。
BLENDER_MCP_WORKDIR	<tmpdir>/three-ws-blender-mcp	ツール呼び出し時に出力パスが明示されていない場合の出力先です。
BLENDER_MCP_ALLOW_PYTHON	1	0 に設定すると、公開されるツール一覧から blender_run_python を完全に除外します。
BLENDER_MCP_MAX_CONCURRENCY	2	同時に実行できる Blender プロセス数です。上限を超えた呼び出しはメモリを奪い合わず、キューに入ります。
BLENDER_MCP_INLINE_IMAGE_PX	768	インラインで返されるレンダー画像コピーの長辺のピクセル数です。フル解像度の PNG は常にディスクに保存されます。
BLENDER_MCP_INLINE_IMAGE_BYTES	1500000	このサイズを超えると画像はディスクに保存され、レスポンスでその旨が示されます。
THREE_WS_BASE	https://three.ws	blender_forge_import のデプロイ先です。
THREE_WS_FORGE_TIMEOUT_MS	600000	1回のテキストから3Dへの生成に対する上限時間です。
THREE_WS_FORGE_PROVIDER_KEY	未設定	ユーザー自身のキーを使うジオメトリ処理用の Meshy／Tripo キーです。デフォルトの画像処理は無料で、キーは不要です。

セキュリティ

blender_run_python は、呼び出し元が指定した Python をこのサーバーの権限で Blender 内で実行します。ローカルファイルシステムの読み書きが可能です。それがこのツールの目的であり、実行前にクライアントが確認を求められるよう、destructiveHint: true が付与されています。無人環境や共有環境でデプロイする場合は、BLENDER_MCP_ALLOW_PYTHON=0 を設定してください。ツールは公開されなくなります。

それ以外はすべてローカルで動作します。ネットワークにアクセスするのは blender_forge_import のみで、THREE_WS_BASE が指定する three.ws のデプロイ先に限られます。

開発

node src/index.js                        # run the server over stdio
npm test                                 # offline invariants + real-Blender integration
npm run inspect                          # open the MCP Inspector against it

test/registration.test.mjs はオフラインで実行され、Blender がインストールされていなくてもパスします。test/blender-session.test.mjs は実際の MCP stdio セッションを通じて、ローカルの Blender を使ってサーバーを動作させます。テスト用フィクスチャも Blender 自身で作成し、Blender がない場合は問題なくスキップします。

関連項目

• integrations/blender/ はアーティスト向けの対応ツールです。GUI 内から three.ws モデルを生成できるサイドバーパネル付きの Blender アドオンです。このパッケージはエージェント向けです。
• @three-ws/scene-mcp は、1つの文から3Dワールド全体を構成します。
• three.ws は Forge パイプラインの基盤となるプラットフォームです。

ライセンス

Apache-2.0