# Roxy Blender MCP

LLM（Claude など）から Blender を操作して、**公式 Blender MCP より高品質なモデルを作る**ための MCP サーバーです。
公式 MCP の機能（Python 実行・画像確認・アセットライブラリ）を含みます。AI による 3D 生成機能は意図的に入れていません。

公式 MCP は「LLM が生の bpy コードを書いて実行し、画像で確認する」設計なので、仕上がりは LLM の書き方次第です。
Roxy は品質のノウハウを **ツール側に組み込んで** あります。LLM が普通に呼ぶだけで、プロのモデラーの定石が適用されます。
具体的には、実寸モデリング、ベベル、法線処理、PBR マテリアル、照明の較正、品質チェック、取り込みモデルの正規化です。

## 公式 MCP との違い

| | 公式 MCP for Blender | Roxy Blender MCP |
|---|---|---|
| モデリング | 生 Python（`execute_blender_code`） | 回転体・押し出し・スイープ・ロフト・管・プリミティブ・メッシュ編集の高レベルツール（Python も併用可）。穴付きパネルは制約付き三角形分割で生成し、縁の巻き込み・膨らみを形状として作る |
| サイズ | LLM 任せ（スケールで伸ばしがち → ベベルが歪む） | すべて実寸のメッシュで生成、スケール 1 のまま |
| エッジ | 何もしなければ鋭角のまま（CG っぽさの主因） | `bevel=` で角度制限ベベル＋法線ハードニング＋自動スムーズ |
| 曲面 | 自前で頂点計算 | 制御点数個からスプライン補間、60°以上の折れ点は自動で角に（底が膨らまない） |
| 配置 | 座標を手計算 | `place_object`（on_top / left_of …）でバウンディングボックス基準に正確に接地 |
| モディファイア | 自前で設定 | 品質デフォルト付き＋スタック自動整列（Boolean/Mirror → Bevel → Subdivision → Weighted Normal） |
| マテリアル | 基本色のみになりがち・sRGB/リニア混同 | **Poly Haven に実写スキャンがある素材はすべて実写を自動使用**（木・合板・古材・コンクリート・石・レンガ・漆喰・粘土・布・ベルベット・革・樹皮・錆・縞鋼板など。色指定は写真のまま色味を調整、`polyhaven='苔むした岩'` のような言葉で任意の Poly Haven テクスチャも選択可、木目は部材の長手方向に自動で揃う）。Poly Haven にスキャンが存在しない素材（鏡面・有色金属、ガラス、樹脂、磁器、塗装、大理石・御影石）とオフライン時のみ手続き版の 58 種プリセット（UV 不要・実寸スケール・部品ごとの個体差）。木は年輪と導管で板目／木口を再現、大理石の網目状の脈、数 mm の鉱物粒の御影石、実寸レンガ、指紋や拭き跡のある金属、フレーク入り車塗装、糸単位の織り目の布、シボ・シワのある革など。sRGB→リニア自動変換 |
| 照明 | 自前 | AgX 前提で露出較正済みの 8 プリセット、被写体サイズに自動スケール |
| 確認 | ビューポート / 多視点 / アニメーション | 同等以上: 正投影（実寸幅表示）＋パースの多視点シート、ワイヤーフレーム・クレイ・X線・マテリアル表示、アニメーションのコマ送り、任意画像の表示 |
| AAA 仕上げ | — | **使用感レイヤー（擦れ・汚れ・ほこり・錆・経年・苔・雪・濡れ・擦り傷。Blender上でスライダー調整可）**、**PBR値の自動補正**、**板張り `add_planks`・レンガ/石積み/タイル `add_masonry`・角の欠け `add_damage`（ジオメトリーノード、つまみ付き）**、**参考画像との形の照合 `compare_reference`**、**自然な散布 `scatter`（小石・瓦礫・葉）**、**ディテール一発追加（分割溝・ネジ・リベット・通気スリット）**、**クッション生成（パイピング・房付き）**、**AAA 基準の自己採点 `review_model`**（優先順の修正リスト付き） |
| 品質チェック | メッシュ/ウェイトの健全性 | 浮き・めり込み・法線反転・内部面・重複頂点・ファセット・未ベベル・スケール未適用・ウェイト漏れなどを検出し、修正方法を提示 |
| 取り込み物の後処理 | サイズ指定程度 | **実寸化・接地・スケール 1・原点を底面中央に・余計なカメラ/ライト除去・重複頂点/スムーズ修正・ポリゴン予算・テクスチャ埋め込み・クレジット記録・自動プレビュー** |
| ブロックアウト連携 | — | Roxy で作った大まかな形を、取り込んだモデルで同じサイズ・位置に差し替え（`fit_to`） |
| アセット | Poly Haven / Sketchfab / Poly Pizza | 同じ 3 ライブラリ＋Sketchfab は**キーなしで検索可**、Poly Haven テクスチャは**実寸スケールで UV 不要の貼り付け**、.blend の非表示の残骸を除外 |
| **アニメーション・リグ** | — | キーごとのイージング（AE の Easy Ease・影響度%、CSS cubic-bezier、back/bounce/elastic）、予備動作・行き過ぎ付きの定番プリセット（開く・閉じる・引き出し・回転・揺れ）、小物の蝶番リグ（開く向き自動判定・可動範囲）、**完成キャラへの自動リグ**（UE5 Mannequin 互換の骨名・指・ねじれ骨・IK骨、服と髪も自動ウェイト、ポーズ検査）、UE5 用 SK_/A_ FBX 書き出し |
| **ゲームアセット化（UE5）** | — | `make_game_asset` 一発で、ハイポリ→ローポリ（誤差0.1%以内のリトポロジー、ネジ等の小部品・ベベル・欠け・板の隙間は法線マップへ、面積加重法線）、AAA 手法の自動 UV（硬い角と見えない場所に継ぎ目、帯の直線化、1024px/m、ライトマップUV）、焼き漏れの自動検査、Blender 専用の質感（Poly Haven・手続き・使用感）を部品ごとに Cycles で焼き付け、BaseColor / Normal（DirectX）/ ORM の PNG、ガラスは別スロット、UCX_ 当たり判定、SM_ 命名・底面中央ピボットの FBX まで。`review_model(purpose='game')` でゲーム基準チェック |
| ファイル入出力 | — | ローカルの glb/gltf/fbx/obj/stl/ply/usd/abc/blend 取り込み、glb/fbx/obj/stl/ply/usd(z) 書き出し（ゲームエンジン・AR・3D プリント） |
| 安全策 | — | チェックポイント保存/復元、GUI では 1 コマンド = 1 アンドゥ |
| ノウハウ | — | 実寸表、ハードサーフェス、オーガニック、家具、プロダクト、マテリアル、照明、アセット活用のガイドと検証済みレシピ |
| テレメトリ | あり（オプトアウト式） | なし |

## 構成

```
Claude ──(MCP stdio)──> roxy-blender-mcp (src/roxy_blender_mcp) ──(TCP 127.0.0.1:9877)──> Blender アドオン (addon/roxy_blender_bridge)
                              │
                              └── HTTPS: Poly Haven / Sketchfab / Poly Pizza（ダウンロードはキャッシュに保存）
```

- **Blender アドオン**: Blender 内でソケットサーバーを起動し、すべての処理をメインスレッド（タイマー）で実行します。
  モデリング・取り込み後処理のロジックはここにあります。ネットワーク通信はしません。
- **MCP サーバー**: ツール定義（LLM 向けの説明文）、アセットライブラリとの通信、ガイド配信を担当します。
- 公式 MCP（ポート 9876）と同時に使えます。

## セットアップ

必要なもの: Blender 4.2 以降（5.1 で検証）、[uv](https://docs.astral.sh/uv/)

1. **アドオンのインストール**（Blender を閉じた状態で）
   ```bash
   python3 scripts/install_addon.py          # シンボリックリンクで導入し有効化
   python3 scripts/install_addon.py --uninstall
   ```
   Blender を起動すると自動でブリッジが立ち上がります（3D ビュー右サイドバーの「Roxy」タブで状態確認・開始/停止）。

2. **Claude Code に登録**
   - このフォルダで使う場合: 同梱の `.mcp.json` が読み込まれます。
   - どこからでも使う場合:
     ```bash
     claude mcp add roxy-blender -s user -- uv run --directory "/path/to/Roxy-Blender-MCP" roxy-blender-mcp
     ```

3. **（任意）アセットライブラリの API キー**（Poly Haven はキー不要。Sketchfab のダウンロードと Poly Pizza のみ）
   ```bash
   uv run roxy-blender-mcp configure     # または環境変数 SKETCHFAB_API_TOKEN / POLYPIZZA_API_KEY
   ```

4. **GUI なしで使う場合**（任意）: `scripts/run_headless_blender.sh [--port 9877] [file.blend]`

## 使い方

Claude に普通に頼むだけです。例:

- 「北欧風のダイニングチェアをモデリングして、プロダクト撮影風にレンダリングして」
- 「リビングを作って。ソファと観葉植物は Poly Haven から、ローテーブルはモデリングで」
- 「この椅子を GLB で書き出して」

MCP プロンプト `model_object` は、品質ワークフロー（計画 → 実寸ブロックアウト → 構造・接合部の詳細化 → 表面仕上げ →
品質チェック → 全体・寄りの画像確認 → レンダリング）を指示します。
標準の制作指示は、対象や用途を問わず、全モデル・全部品を接写に耐える精密さで作り込むよう促します。
キャラクター・自然物・衣服・機械・家具・建築・小物に共通して適用し、背景用という理由だけでは省略しません。
簡略化は、ラフ・低詳細・ポリゴン予算などをユーザーが明示した場合に限ります。
地域の指定がなければ、日本で一般的な形状・寸法・構造・部品・生活用品・植生を基準にし、看板やラベルも日本語を基本にします。
日本基準は厳格な制作要件です。輸入アセットや背景の部品にも適用し、海外仕様や汎用寸法での代用を禁止する指示を入れています。
`get_guide('japan')` に従い、地域依存の細部は日本の参考資料を確認してから作ります。
不明・不確かな点はまず AI クライアントの検索・ブラウザでメーカー資料や公式情報を調べ、調査でも解決できない場合や調査手段がない場合に限って質問します。
Roxy 自体には汎用 Web 検索ツールはなく、接続する AI 側の調査ツールを使う指示です。
未確認の箇所は未完成として報告し、納品前に日本仕様との一致を画像で確認します。自動の形状判定・強制機能ではありません。
現代の題材には現代日本の例を使い、伝統的な意匠は題材に合わせて選びます。明示された国・様式・固有の対象・参考画像を優先します。
`get_guide('detailing')` には、肉厚・継ぎ目・取り付け部の設計、形状とバンプの使い分け、部位ごとの確認手順をまとめています。
指示とガイドによる改善なので、完成度は実際のモデルと画像で確認します。

`modeling_progress` は部位ごとに「参照資料 → 形状 → 構造 → 細部 → 材質 → 最終確認」を記録するツールです。
最初に `define_features` で部位の特徴的な輪郭・開口・接続先を整理し、資料の出典、保存した参照画像、対象オブジェクト、確認ビューを登録します。実物の写真や図面を使い、ペーパークラフト・模型の簡略化を形状根拠にしません。
`compare_features` では接写で観察した形と資料との差異を記録します。不合格から合格にするには、`record_revision` に実際の修正または誤った観察を訂正する根拠を残し、新しい画像で再確認する必要があります。未修正の特徴、未解決の資料、前工程を飛ばした合格は完成判定を通しません。
`inspect_connections` は配管・連結棒などの指定した端点と接続先の評価済み形状との距離を測ります。穴を含む実際の表面を使い、端点が部品自身の表面にあるかも検査します。特徴に `connection_checks` を登録すると、合格の記録時にも自動で測定し、隙間が許容値を超えていれば合格を拒否します。ジョイント中心同士の検査も可能です。接続相手の正しさ、干渉、機構の動作は別途確認します。
登録した対象の形状・材質入力と画像を指紋で追跡し、確認後の変更や根拠画像の消失で完成判定を止めます。`invalidate` で後続工程と全体の最終確認を戻せます。記録は .blend に保存されるため、根拠画像も制作フォルダに保存してください。
画像の内容を自動理解する機能ではありません。未登録の部品、外部テクスチャや入れ子のシェーダーなど全依存関係の変更検出は保証しません。AI が実際の資料と接写を比較する必要があります。旧バージョンの進捗記録にも特徴の登録・確認が必要です。詳しい制作例は `get_guide('reference_fidelity')` にあります。

## ツール一覧（58）

| 分類 | ツール |
|---|---|
| 確認 | `get_status`, `get_scene_info`, `inspect_object`, `look`, `viewport_screenshot` |
| 形状作成 | `create_primitive`, `create_lathe`, `create_extrusion`（穴・縁の巻き込み・プレスの膨らみ）, `create_sweep`, `create_loft`（断面の上下非対称・丸い端・ねじれない対応）, `create_pipe`（太さが連続的に変わる管・曲げ半径・肉厚）, `create_text` |
| 編集 | `edit_mesh`, `add_modifier`, `manage_modifiers` |
| 配置・整理 | `transform_object`, `place_object`, `duplicate_pattern`, `organize_objects`, `clear_scene` |
| マテリアル | `apply_material`, `list_material_presets`, `uv_unwrap`, `uv_report` |
| 演出 | `setup_lighting`, `create_backdrop`, `setup_camera`, `render_image` |
| アセット・入出力 | `search_assets`, `import_asset`, `import_model_file`, `export_model` |
| AAA 仕上げ | `add_surface_detail`, `add_planks`, `add_masonry`, `add_damage`, `create_cushion`, `review_model`, `compare_reference`, `scatter` |
| ゲームアセット | `make_game_asset` |
| アニメーション・リグ | `animate`, `animate_preset`, `check_animation`, `rig_prop`, `rig_character`, `export_skeletal` |
| 品質 | `analyze_quality`, `cleanup_mesh`, `modeling_progress`, `inspect_connections`, `check_contacts`（どこにも付いていない部品・宙で終わるケーブルやステーの端を実表面で検出。床に立つ部品は接地扱い）, `attach_part`（隙間を閉じる：移動・方向指定移動・端の延長・表面への沿わせ。別部品へのめり込みが生じる移動は取り消して拒否）, `declare_free`（意図的に開いた端・独立した付属品を理由付きで宣言） |
| 安全策・拡張 | `checkpoint`, `execute_python`, `batch`, `get_guide` |

ガイド（`get_guide` / `guide://` リソース）: workflow, dimensions, hard_surface, organic, furniture, product,
detailing, reference_fidelity, japan, materials, lighting_render, assets, game_assets, animation_rigging, recipes, troubleshooting

## テスト

```bash
B=/Applications/Blender.app/Contents/MacOS/Blender
$B --background --factory-startup --python tests/blender_progress_test.py                 # 部位別進捗・保存
$B --background --factory-startup --python tests/blender_fidelity_test.py                 # 修正・再確認・接続の検査
uv run python tests/e2e_fidelity_test.py                                                  # 新しい手順を MCP 経由で検証
$B --background --factory-startup --python tests/blender_commands_test.py -- /tmp/roxy_out   # 全モデリングコマンド
$B --background --factory-startup --python tests/blender_recipes_test.py -- /tmp/roxy_out    # レシピ 6 種を実行・レンダー
$B --background --factory-startup --python tests/blender_import_test.py -- /tmp/roxy_out     # 取り込み後処理・書き出し
uv run python tests/e2e_mcp_test.py [--gui]       # MCP クライアント → サーバー → Blender
uv run python tests/e2e_assets_test.py            # アセットライブラリ（Sketchfab/Poly Pizza はモック、Poly Haven は本番 API）
```

`tests/mock_services.py` は Sketchfab / Poly Pizza の API 仕様どおりに応答するモックです（キーなしで実装経路を検証）。

## 新規モデリング比較

> 比較の記録（画像・モデル・評価資料・参考写真）は、第三者の写真や比較先のコードを含むためこのリポジトリには含めていません。`bench/` には再現用のスクリプトのみがあります。

強化後の再比較では、別題材の **1969 ホンダ CB750 FOUR K0** を、同じHonda実車資料・25分上限で設計から独立に新規制作しました。MCP名を伏せた固定8項目（各0〜4）のアシスタント評価は、比較先17/32、Roxy14/32です。Roxyの品質優位は出ていません。サイドカバーの面割れ・タンク下部の凹凸・マフラー形状に相違が残りました。比較先の自己レンダー中断・復旧時間も制作枠に含めています。Roxyの完成判定は未通過です。単一試行であり、前のC62とは題材が違うため改善率は計算しません。

共通撮影の再現: `Blender --background --factory-startup --python bench/cb750_render.py -- official` と同じコマンドの `roxy`、その後 `python3 bench/prepare_cb750_review.py`。匿名評価後に `python3 bench/plot_cb750_comparison.py`。原本・入力・MCPコードの保持確認は `uv run python bench/audit_cb750_trial.py`。

以下は強化前の比較です。

前回の比較では、C62形2号機を**設計から独立に制作**しています。同じ実車写真・博物館の寸法・制作時間枠を別文脈の制作担当へ渡し、共通の組立設計や前回のモデルを使用しません。Roxy側は比較実施時点の指示・プロンプト・ガイド・ツール、比較側はahujasid版の指示・ツールを使用します。完成物を共通撮影し、MCP名を伏せた別担当の写真照合で評価します。特徴比較・修正履歴・接続の測定ゲートを追加する前の結果であり、今回の強化後の品質を示す比較ではありません。

これは単一題材・各1試行のアシスタント評価で、統計的な優位やAAA品質の認定ではありません。部品数・三角形数を品質点に換算しません。以下は以前の**共通設計による制作経路比較**です。

さらに複雑な題材として、C62形2号機の実車写真と京都鉄道博物館の寸法資料を参考に、機関車・炭水車1,747部品と線路303部品を新規制作しました。動輪の実開口、連結棒・ピストンの連動、配管、葉ばね、運転室、炭水車を含みます。ペーパークラフトや模型は形状の参考にしません。

再現: `uv run python bench/live_c62_compare.py`、続けて matplotlib / Pillow のある環境で `python3 bench/plot_c62_comparison.py`。

より複雑な題材として、日本信号 GX-7 の国内資料を参考にした自動改札機2台を両MCPで新規制作しました。394部品で、曲面筐体、券口の実際の切り込み、IC読取部、表示器、保守扉、ネジと溝、センサ、換気スリット、開閉するフラップを含みます。材質はそれぞれの制作経路で作り、撮影条件と実測だけを共通にしました。部品数・三角形数は品質点ではありません。

再現: `uv run python bench/live_gate_compare.py`、必要に応じて `Blender --background --python bench/audit_gate_views.py` で単色ビューを再描画し、続けて matplotlib / Pillow のある環境で `python3 bench/plot_gate_comparison.py`。Blenderの起動時ダイアログがある場合は新規起動を選びます。これは同じ担当者による同仕様の制作経路比較で、AIの独立した自律制作能力やAAA品質の認定ではありません。比較先は ahujasid 版で、Blender Foundation公式MCPではありません。

2026-10-07 に、日本の一合枡を現在の Roxy と ahujasid 版 MCP for Blender の実際のサーバー経由で新規制作しました。
同じ設計・材質・撮影条件では、幾何チェックは双方 7/7、独自スコアは双方 80、三角形数は比較対象 6,316 / Roxy 7,212 でした。
この1課題から品質優位や AAA 品質達成は結論できません。AI の独立した自由制作比較ではなく、同じアシスタントが制作コードを作る比較です。

古い宝箱のグラフは異なる制作レシピを Roxy 経由で実行した保存結果で、今回の同仕様・実サーバー比較とは条件が異なります。

レンダー・プレビュー・チェックポイントは OS の一時フォルダの `roxy_blender_mcp/` に保存されます（`get_status` の
`work_dir`）。ダウンロードは `~/Library/Caches/roxy-blender-mcp/` にキャッシュされます。

## ライセンス

GPL-3.0-or-later（Blender アドオンの要件に合わせています）。取り込んだアセットのライセンスは各提供元に従います
（CC-BY はクレジット表記が必要。オブジェクトのカスタムプロパティ `roxy_license` / `roxy_author` に記録されます）。