BlenderLens

BlenderLens

AI エージェントが、単一のオブジェクトからアニメーション付きのシーン全体まで、Blender でモデリング、テクスチャ作成、アニメーションを行える MCP サーバーです。エージェントの作業を自分の Blender ウィンドウで見ながら、実行した操作を元に戻せます。または、ウィンドウを表示せず、バックグラウンドの Blender で作業させることもできます。成果物は通常の .blend ファイル、または必要な形式でエクスポートできます。

BlenderLens を通じて AI エージェントが Blender で作成した短いアニメーションシーンを、2倍速で表示しています。

できること

サーバーを接続したら、作りたいものを説明するだけで、エージェントが Blender で作成します。BlenderLens を使うと、次のことができます。

• モデリング：プリミティブ、パスに沿ったチューブ、回転体のプロファイル、3D テキスト、または頂点データから始めて、押し出し、インセット、ベベル、二等分、ソリッド化、細分化を行ったり、任意の Blender モディファイアーを追加したりできます。
• テクスチャ作成：エミッションや透明度を持つ PBR マテリアル、頂点カラー、UV 展開に加え、ベイクしたカラー、アンビエントオクルージョン、法線、ライティングのテクスチャを作成できます。
• アニメーション：移動、回転、スケール、シェイプキーを名前付きクリップにキーフレームとして設定できます。
• シーンの組み立て：オブジェクトを配置、親子付け、複製、グループ化し、下にあるものの上で静止するまで落下させられます。
• 作業の確認：任意の角度からプレビューをレンダリングしたり、シェーディング、クレイ、ワイヤーフレームの各スタイルで複数視点のシートを作成したりできます。
• チェック：パーツを計測し、互いに貫通しているものを見つけ、壊れたジオメトリを事前に検出できます。
• 納品：.blend を保存するか、glTF、FBX、OBJ、STL、PLY、USD にエクスポートできます。既存のモデルをインポートしたり、独自のビルドスクリプトを実行したりすることもできます。

AI エージェント向けに設計

エージェントはすでに Python を書いて Blender を操作できますが、結果を見ることができず、確認できないジオメトリを推測し、ファイルを開くまで問題に気づけません。BlenderLens は、Blender でモデリングする人が得られるフィードバックをエージェントにも提供します。

Blender Python を直接書くエージェント	BlenderLens を使うエージェント
作成したものを確認できない	任意の角度からプレビューをレンダリングしたり、複数視点のシートを作成したりして、内容を確認できます
bmesh コードを書き、どの面を編集するか推測する	面の向きに基づいて選択した面を押し出し、ベベル、インセットし、作成した面を取得できます
パーツが接触しているか、互いに貫通しているか判断できない	距離や重なりを計測し、下にあるものの上で静止するまでオブジェクトを落下させられます
壊れたジオメトリ、適用されていないスケール、配置のずれた原点を見つけるのはあなた	該当する面とともに check_asset で検出します
エクスポーターから {'FINISHED'} を受け取るだけで、それ以上はわからない	ディスクからすべてのエクスポートを読み戻し、ファイルの内容を報告します
簡単には取り消せない変更を加える	変更のたびに元に戻す操作が1段階分作成されます

2つの実行方法

• Blender ウィンドウ内で実行：BlenderLens アドオンをインストールして Start を押すと、エージェントは起動中の Blender で作業します。変更が行われるたびに確認でき、いつでも作業に介入できるほか、Ctrl+Z を押してどの呼び出しも元に戻せます。
• バックグラウンドで実行：アドオンがなくても、サーバーは必要な最初の呼び出し時に blender --background を起動し、サーバーの終了まで実行し続けます。Blender 側での設定は不要です。

デフォルトでは、アドオンが起動している場合はサーバーがウィンドウを使い、それ以外の場合はバックグラウンドの Blender を使います。

必要条件

	必要な用途
Blender 4.2 LTS 以降（4.2 および 5.0 でテスト済み）	すべて。BLENDER_BIN、PATH、または通常のインストール先フォルダーから検出されます
Python 3.10 以降、または npx 用の Node.js 18 以降	依存関係のないこのサーバーの実行
Blender の BlenderLens アドオン	Blender ウィンドウで作業する場合のみ

GPU は不要です。プレビューとベイクは CPU 上の Cycles でレンダリングされます。

インストール

npx（推奨）。パッケージにはサーバーが含まれており、PATH に Python 3.10 以降が必要です。

{
  "mcpServers": {
    "blenderlens": {
      "command": "npx",
      "args": ["-y", "blenderlens-mcp"],
      "env": { "BLENDER_BIN": "C:\\Program Files\\Blender Foundation\\Blender 5.0\\blender.exe" }
    }
  }
}

pip

pip install blenderlens-mcp

{
  "mcpServers": {
    "blenderlens": { "command": "blenderlens-mcp", "env": { "BLENDER_BIN": "/path/to/blender" } }
  }
}

Claude Code では、プロジェクトの .mcp.json に設定します。バックグラウンドモードに必要なのはこれだけです。

Blender アドオン

Blender ウィンドウで作業するには、アドオンをインストールします。

blenderlens-mcp install-addon       # or: npx -y blenderlens-mcp install-addon; --blender PATH picks the Blender

次に、3D ビューポートで N を押し、BlenderLens タブを開いて Start を押します。アドオンはこのマシン上でのみ待ち受け、トークンを保持するサーバーだけに接続します。トークンはアドオンがファイルに書き込み、サーバーがそのファイルを読み取ります。アドオンは各 GitHub リリースにも zip ファイルとして添付されています。

エージェントの仕組み

ツールは、次のサイクルを中心に構成されています。

flowchart LR
    B["<b>Build</b><br/>create_object<br/>edit_mesh<br/>set_material"]
    L["<b>Look</b><br/>render_preview<br/>get_object"]
    C["<b>Check</b><br/>check_asset<br/>measure_objects"]
    D["<b>Save</b><br/>save_file<br/>export_file"]

    B --> L --> C --> D
    L -- "not right yet" --> B
    C -- "an issue" --> B

    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    class B,L,C,D step;

1. 作成。 create_object でパーツを作成し、edit_mesh で形状を整え、set_material で色を付け、animate_object で動かします。join_objects と set_parent でパーツを組み立てます。既存のビルドスクリプトは run_script でそのまま実行できます。
2. 確認。 render_preview でパーツ、または複数の角度から見たシートをレンダリングし、エージェントが PNG を確認します。get_object では正確なサイズと数を取得できます。
3. 検査。 check_asset で、壊れたジオメトリ、未適用のスケール、位置のずれた原点、UV とテクスチャの問題、パーツ同士の貫通を検出します。measure_objects では、何が何に接触しているかを確認できます。
4. 保存。 save_file で .blend を保存し、export_file と export_glb で他の形式に書き出してから、ファイルを読み戻します。

ツール

単位はメートル、回転は度数で、Z が上方向です。面インデックスは get_mesh が列挙するもので、面を追加または削除する編集を行うと変わります。

セッション

ツール	説明
get_status	サーバーが使用している Blender と、その処理状況を、Blender を起動せずに確認します。動作がおかしい場合は、まずこれを使ってください。
open_session	アドオンを実行中の Blender ウィンドウに接続するか、バックグラウンドで Blender を起動します。必要に応じて .blend を開くこともできます。
close_session	接続を切断します。バックグラウンドの Blender は終了し、ウィンドウは開いたままになります。discard を指定しない限り、未保存の変更がある場合は拒否されます。

検査

ツール	説明
get_scene	各オブジェクトの種類、親、位置、寸法、数、マテリアル、モディファイアーを表示します。
get_object	1 つのオブジェクトの詳細を表示します。トランスフォーム、境界、モディファイアー適用前後の数、各モディファイアーの設定が含まれます。
get_mesh	オブジェクトの面について、インデックス、中心、法線、面の向き、マテリアルを表示します。ほかのツールが受け取るインデックスも含まれます。
list_materials	各マテリアルの値と、それを使用しているオブジェクトを表示します。

作成

ツール	説明
create_object	プリミティブ、パスに沿ったチューブ、回転体のプロファイル、3D テキスト、または空のオブジェクトを作成します。サイズはメッシュに適用されるため、スケールは 1 のままです。
create_mesh	プリミティブでは作成できない形状を、頂点と面から作成します。
edit_mesh	インデックスまたは面の向きで選択した面に、押し出し、差し込み、ベベル、二等分、ソリッド化、細分化などを行います。
add_modifier	Blender 独自の名前で設定を指定して、任意の Blender モディファイアーを追加します。
set_modifier	モディファイアーの設定、スタック内の位置、表示状態を変更します。
apply_modifier	モディファイアーの結果をメッシュに適用します。
remove_modifier	適用せずにモディファイアーを削除します。
set_material	オブジェクトまたは選択した面に、発光、透明度、カリング、画像を設定した PBR マテリアルを作成または更新します。
set_vertex_color	面に色属性をペイントします。
unwrap_uv	UV マップに展開し、アイランド、重なり、テクセル密度を報告します。
bake_texture	Cycles で色、アンビエントオクルージョン、法線、発光、または全ライティングを PNG にベイクし、マテリアルに接続します。
join_objects	メッシュを 1 つのパーツに結合し、各ピースのマテリアルを維持します。
animate_object	トランスフォームとシェイプキーを名前付きクリップにキーフレームとして設定します。
create_collision	ゲームエンジンの物理演算向けに、ボックス、凸形状、または簡略化した衝突プロキシを作成します。

配置

ツール	説明
set_transform	位置、回転、スケール、または寸法を設定します。drop を指定すると、オブジェクトは下にあるものに接するまで落下します。
apply_transform	回転とスケールをメッシュに適用するか、たとえば原点を底面の中央に移動します。
set_parent	ワールド位置を維持したまま、親を設定または解除します。
set_collection	オブジェクトをコレクションに移動します。
set_object	名前の変更、非表示、カスタムプロパティの設定を行います。
duplicate_object	モディファイアー、マテリアル、子オブジェクトを含めてオブジェクトを複製します。
delete_object	オブジェクトを削除します。

確認と表示

ツール	説明
check_asset	オブジェクトがエクスポートされる状態を確認します。必要に応じて、三角形の budget とプロジェクトの rules に照らして確認します。passed と、各問題およびその面を返します。何も変更しません。
measure_objects	パーツ間の距離、接触・重なり・内包の有無、またはシーン内へのレイキャストを確認します。
render_preview	名前付きビューまたは任意の角度から、フレームに収めた PNG を生成します。複数のビューを 1 枚の画像にまとめることもできます。シェーディング、クレイ、ワイヤーフレーム、パーツごとの色分けスタイルに対応し、周囲のオブジェクトをコンテキスト表示したり、カットアウェイ用にカメラからオブジェクトを隠したり、幅を固定した正投影ビューを使用したりできます。シーンは変更されません。

ファイル

ツール	説明
save_file	.blend またはチェックポイントのコピーを保存します。
open_file	.blend を開きます。
create_file	新しい空のファイルを作成します。
import_file	glTF、OBJ、FBX、STL、PLY ファイルをインポートするか、.blend からオブジェクトを追加します。
export_file	FBX、OBJ、STL、PLY、USD を書き出し、読み戻します。
export_glb	.glb（バイナリ glTF）を書き出して読み戻し、Godot または three.js での表示について警告します（以下を参照）。

Python と元に戻す

ツール	説明
run_python	Blender 内で Python を実行します。どのツールでも対応できない処理に使用します。
run_script	ビルドスクリプトファイルを実行します。ヘルパーモジュールもインポートできます。
undo_change	シーンを変更した呼び出しを、1 回につき 1 つずつ元に戻します。

glTF のエクスポート

export_glb は .glb を書き出した後、書き出したファイルを開き、実際に含まれている内容を報告します。ノードツリー、三角形の数、マテリアル、描画呼び出し数とテクスチャメモリの推定値が含まれます。また、ファイルに含まれていないオブジェクト、メッシュなしで書き出されたメタボール、適用したモディファイアーによって削除されたシェイプキー、必要な UV がないテクスチャ、タンジェントがないノーマルマップなど、処理中に失われたものについて警告します。

target はファイルを読み込むエンジンを指定し、それに応じた警告を返します。godot、threejs、または（デフォルトの）generic を指定でき、generic では両方の警告が返されます。

• Godot：インポートヒントとして読み取る名前（Rock_col はコリジョンボディになります）、名前をもとにループ再生するアニメーション、名前を変更するノード、読み込めない拡張機能、Godot 4.7.0 から 4.7.2 がメッシュの最初のプリミティブで無視する頂点カラーです。Godot はインポートできないため、Draco 圧縮は拒否されます。
• three.js：GLTFLoader が読み込めない拡張機能、またはアプリ側でデコーダーを設定しないと読み込めない拡張機能です。create_collision で作成したコリジョンプロキシは、three.js では描画されるため除外されます。

プロジェクトのルール

一連のモデルで同じ規約に従う必要がある場合、check_asset を使って、それぞれに三角形数の上限と、インラインまたは rules_file で指定した独自ルールを適用できます。ルールは JSON オブジェクトで、各キーは省略可能です。

キー	失敗する条件
required	指定した名前のオブジェクト、または "Parent/Child" パスが存在しない
single_root	アセットにルートオブジェクトがちょうど 1 つない
retired	オブジェクトまたはマテリアルの名前が、プロジェクトで使用されなくなった名前である
palette, palette_only	マテリアルの色または値がパレットと異なる、またはマテリアルがパレットに含まれていない
extras	カスタムプロパティがない、または型が正しくない
size	オブジェクトの寸法がメートル単位で指定範囲外である
origin_at_base	オブジェクトの原点が底面にない
budget	アセット全体、または指定したパーツの三角形数が多すぎる
apart	互いに接触してはいけない 2 つのパーツが貫通している

名前には、"re:<regular expression>" の形式でパターンも指定できます。examples/rules.json はルール一式の例です。また、examples/build_lantern.py では、サーバーを通してプロップを最初から最後まで作成、チェック、エクスポートします。

同じチェックは、たとえばビルドパイプラインなど、エージェントなしでも実行できます。.glb は Blender なしで読み込まれ、.blend はバックグラウンドの Blender で開かれます。--target を指定するとそのエンジンの警告が追加され、--json を指定すると結果全体が出力されます。モデルがチェックに合格した場合、コマンドは終了コード 0、失敗した場合は 1、チェックできなかった場合は 2 で終了します。

blenderlens-mcp check lantern.glb --budget 2000 --rules rules.json

エラー

ツールが呼び出しを拒否すると、何も変更せず、error（何が問題だったか）、exit（種類ごとに固定された番号）、kind、hint（対処方法）を返します。

Exit	Kind	意味
1	blender_error	呼び出しの実行中に Blender でエラーが発生しました
2	not_found	呼び出しに必要なオブジェクト、マテリアル、ファイル、ジオメトリが存在しません
3	bad_argument	Blender で使用できない値がパラメーターに指定されています
4	python_error	run_python または run_script で実行したコードが例外を発生させました
5	unsaved_changes	開いているファイルに未保存の変更があります。先に保存するか、discard を指定してください
6	blender_missing	Blender の実行ファイルが見つかりませんでした
7	not_connected	BlenderLens アドオンから応答がありませんでした
8	connection_lost	呼び出し中に Blender が終了またはクラッシュしたか、アドオンが停止しました
9	start_failed	バックグラウンドの Blender を起動できませんでした
10	version_mismatch	アドオンが別のプロトコルバージョンを使用しています。再インストールしてください
11	token_mismatch	アドオンがサーバーのトークンを拒否しました
12	busy	Blender は前の呼び出しの処理中です
13	not_allowed	Python が無効になっているか、パスが BLENDERLENS_ALLOWED_DIRS の範囲外です
70	internal_error	BlenderLens 自体で障害が発生しました
124	deadline	Blender が時間内に応答しませんでした。処理を続けている可能性があります

制限事項

• Python に制限はありません。 run_python と run_script は、Blender 内で Python で可能なあらゆる操作を実行でき、Blender を終了させることもできます。必要に応じて BLENDERLENS_ALLOW_PYTHON=0 を設定するか、アドオンで Allow Python from the agent をオフにしてください。
• drop は頂点で支持点を検出します。 たとえば、棒が別の棒の上に横たわる場合のように、辺同士の接触だけがあると、支持点は検出されず、オブジェクトはそのまま落下します。
• ノードグループ内の Principled BSDF は BlenderLens から認識できないため、そのマテリアルの値は変更されません。
• Blender のウィンドウでは、プレビューを行うとファイルに変更があるとマークされます。 Blender は、レンダーエンジンを同じものに戻す場合でも、設定するたびに変更があったと判断するためです。
• Blender の glTF エクスポーターは、メタボールを空のノードとして書き出します。 check_asset はメタボールをエラーとして報告し、export_glb は警告します。

アーキテクチャ

flowchart TD
    Agent["AI Agent"]
    BL["<b>BlenderLens</b><br/>MCP server<br/>Python 3.10+<br/>no dependencies"]

    Agent <-- "stdio, JSON-RPC 2.0" --> BL

    BL -- "TCP 9877<br/>with its token" --> Window
    BL -- "starts and owns" --> Background

    Window["<b>Blender window</b><br/>add-on started<br/><i>you watch, and can undo</i>"]
    Background["<b>blender --background</b><br/>no window<br/><i>lives as long as the server</i>"]

    classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    classDef blender fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;
    class Agent,BL svc;
    class Window,Background blender;

どちらの方法でも同じコマンドコードが Blender のメインスレッド上で実行されます。メッシュ処理には bmesh を使用するため、ウィンドウの有無にかかわらず同じように動作します。シーンを変更する各呼び出しは、1 回の取り消し操作になります。MCP プロトコルと Blender への接続は Python 標準ライブラリを基盤としているため、このパッケージには 実行時依存関係がありません。docs/architecture.md ではモジュールの構成を説明し、docs/decisions/ では各部分をそのように構築した理由を記録しています。

設定

変数	デフォルト	説明
BLENDER_BIN	auto	バックグラウンドセッション、check、install-addon で使用する Blender 実行ファイル
BLENDERLENS_MODE	auto	auto（アドオンの起動時はウィンドウ、それ以外はバックグラウンド）、live（ウィンドウのみ）、または background
BLENDERLENS_HOST	127.0.0.1	サーバーがアドオンに接続する先：localhost またはループバック IPv4 アドレス
BLENDERLENS_PORT	9877	アドオンのポート。アドオンの設定で指定します
BLENDERLENS_TOKEN	アドオンのファイルから取得	サーバー用にアドオンが書き込むトークンを上書きします
BLENDERLENS_TIMEOUT	120	1 回の呼び出しを待機する秒数。render_preview、bake_texture、run_python、run_script では timeout も指定できます
BLENDERLENS_START_TIMEOUT	90	バックグラウンドの Blender の起動を待機する秒数
BLENDERLENS_RENDER_DIR	一時フォルダー	path が指定されていない場合にプレビューを保存する場所。デフォルトのフォルダーでは 7 日間保持されます
BLENDERLENS_ALLOW_PYTHON	1	0 にすると run_python と run_script が削除されます
BLENDERLENS_ALLOWED_DIRS	未設定	ツールに渡すすべてのパスが含まれている必要があるフォルダー。Windows では ;、その他の環境では : で区切ります
BLENDERLENS_RUNTIME_DIR	ユーザーごと	アドオンのトークンファイルと、未保存のバックグラウンド作業の復旧用コピーを保存する場所

ライセンス

Apache License 2.0 — LICENSE と NOTICE を参照してください。BlenderLens は Blender Foundation と提携しておらず、 同財団からの推奨も受けていません。