# BONSAI MCP — インストールガイド
**Claude Desktop ↔ Blender/BONSAI 接続ツール**
HomeStructure LLC | v0.1.1
—
## これは何？
BONSAI MCP は、**Claude Desktop（または Claude対応エディタ）から Blender を直接操作**できるブリッジツールです。
Claude に「シーンにある壁の一覧を見せて」「このコードを Blender で実行して」と自然言語で指示するだけで、Blender 内部の bpy API を完全に活用できます。
“`
┌──────────────┐ stdio ┌──────────────────┐ TCP:9877 ┌──────────────┐
│ Claude │ ◄────────► │ hs_mcp_server.py │ ◄──────────► │ Blender │
│ Desktop │ (MCP) │ (外部Python) │ length+json │ bonsai_mcp │
└──────────────┘ └──────────────────┘ │ (addon) │
└──────────────┘
“`
—
## 必要な環境
| 項目 | 要件 |
|——|——|
| **OS** | Windows 10/11（Mac/Linux でも動作するが本ガイドは Windows 向け） |
| **Blender** | 4.0 以上（推奨: 4.2 LTS 以上） |
| **BONSAI addon** | IFC/BIM 機能を使う場合のみ必要 |
| **System Python** | 3.10 以上（Blender 内蔵 Python とは別） |
| **Claude Desktop** | 最新版 |
> **注意**: Blender に内蔵されている Python は使えません。必ず別途 Python をインストールしてください。
—
## Step 1: System Python の準備
### 1-1. Python がまだない場合
[python.org](https://www.python.org/downloads/) から Python 3.10 以上をダウンロード・インストール。
インストール時に **「Add Python to PATH」にチェック**を入れてください。
### 1-2. 確認
コマンドプロンプトまたは PowerShell で：
“`cmd
python –version
“`
`Python 3.10.x` 以上が表示されれば OK。
### 1-3. mcp パッケージのインストール
“`cmd
pip install mcp
“`
> `mcp` パッケージには FastMCP が含まれています。これが MCP Server の本体です。
—
## Step 2: Blender アドオンのインストール
### 2-1. フォルダ構成
配布 ZIP を展開すると以下の構成になります：
“`
bonsai_mcp/
__init__.py ← アドオン登録
server.py ← Blender 内 TCP サーバー
“`
### 2-2. インストール方法
**方法 A — Blender の UI から（推奨）**
1. Blender を開く
2. `Edit` → `Preferences` → `Add-ons`
3. 右上 `▼` ドロップダウン → `Install from Disk…`
4. `bonsai_mcp.zip` を選択
5. インストール後、`BONSAI MCP` を検索してチェックを入れて有効化
**方法 B — 手動コピー**
1. Blender のアドオンフォルダを開く：
– Windows: `%APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\`
– Mac: `~/Library/Application Support/Blender/<version>/scripts/addons/`
– Linux: `~/.config/blender/<version>/scripts/addons/`
2. `bonsai_mcp/` フォルダをそのまま配置
3. Blender を再起動
4. `Preferences` → `Add-ons` で `BONSAI MCP` を有効化
### 2-3. 動作確認
3D Viewport のサイドバー（`N` キー）に **HS-MCP** タブが表示されれば成功。
> アドオンは .blend ファイルの読み込み時に自動で Bridge を起動します（Auto-start）。手動起動も HS-MCP パネルの「Start Bridge」ボタンから可能です。
—
## Step 3: 外部 MCP サーバーの配置
### 3-1. ファイル配置
`hs_mcp_server.py` を任意のフォルダに置きます。例：
“`
C:\Tools\bonsai-mcp\hs_mcp_server.py
“`
> このファイルは Blender の外で System Python が実行するものです。Blender のアドオンフォルダには入れないでください。
### 3-2. 動作テスト（任意）
Blender でアドオンが起動している状態で：
“`cmd
python C:\Tools\bonsai-mcp\hs_mcp_server.py
“`
`BONSAI MCP Server starting (Blender target: localhost:9877)` と表示されれば接続成功。`Ctrl+C` で終了。
—
## Step 4: Claude Desktop の設定
### 4-1. 設定ファイルの場所
**通常版（インストーラー版）の場合：**
“`
%APPDATA%\Claude\claude_desktop_config.json
“`
**Microsoft Store（MSIX）版の場合：**
“`
%LOCALAPPDATA%\Packages\Claude_<ランダム文字列>\LocalCache\Roaming\Claude\claude_desktop_config.json
“`
> MSIX 版は `%APPDATA%\Claude\` に書き込んでも Claude Desktop からは見えません。必ず Packages フォルダ内の config を編集してください。
**MSIX版のフォルダ特定方法：**
PowerShell で以下を実行：
“`powershell
Get-ChildItem “$env:LOCALAPPDATA\Packages” | Where-Object { $_.Name -like “Claude*” }
“`
### 4-2. 設定内容
`claude_desktop_config.json` を開き（なければ新規作成）、以下を記述：
“`json
{
“mcpServers”: {
“hs-blender”: {
“command”: “python”,
“args”: [
“C:/Tools/bonsai-mcp/hs_mcp_server.py”
],
“env”: {
“BLENDER_PORT”: “9877”
}
}
}
}
“`
> **パスの注意点:**
> – `command` には System Python のフルパスを指定することを推奨。
> 例: `”C:/Users/YourName/AppData/Local/Programs/Python/Python313/python.exe”`
> – `args` の .py ファイルパスもフルパスで指定
> – パス区切りは `/`（スラッシュ）を使用（バックスラッシュ `\` は JSON でエスケープが必要）
### 4-3. Claude Desktop を再起動
設定を保存後、Claude Desktop を完全に閉じて再起動してください。
—
## Step 5: 接続テスト
1. **Blender** を起動（アドオンが自動で Bridge を起動）
2. **Claude Desktop** を起動
3. Claude に以下のように話しかける：
“`
Blenderのシーン情報を教えて
“`
シーン内のオブジェクト一覧が返ってくれば、セットアップ完了です。
—
## 利用可能なツール
| ツール | 説明 |
|——–|——|
| `ping` | Blender との接続確認 |
| `get_scene_info` | シーン全体の情報（オブジェクト名・タイプ・位置・IFCクラス） |
| `get_object_info` | 特定オブジェクトの詳細（メッシュ・マテリアル・IFC） |
| `get_ifc_info` | IFC/BIM プロジェクト概要（スキーマ・要素数） |
| `execute_blender_code` | 任意の Python コードを Blender 内で実行 |
—
## トラブルシューティング
### Claude に「Blender に接続できません」と言われる
1. **Blender が起動しているか確認** — アドオンは Blender 起動中のみ動作します
2. **Bridge が起動しているか確認** — 3D Viewport サイドバー → HS-MCP タブ → 「Running」と表示されているか
3. **ポート番号の一致** — Blender 側（デフォルト 9877）と `claude_desktop_config.json` の `BLENDER_PORT` が同じか
4. **ファイアウォール** — localhost:9877 の通信がブロックされていないか
### Claude Desktop で MCP ツールが表示されない
1. `claude_desktop_config.json` のパスが正しいか（特に MSIX 版に注意）
2. JSON の構文エラーがないか（カンマの過不足など）
3. `python` コマンドが正しい Python を指しているか（`python –version` で確認）
4. `mcp` パッケージがインストールされているか（`pip show mcp`）
5. Claude Desktop を完全に再起動したか
### Python の `mcp` パッケージが見つからない
“`cmd
pip install mcp
“`
> 環境によっては `pip3` が必要です。また、複数の Python がインストールされている場合は、`claude_desktop_config.json` の `command` でフルパスを指定してください。
### ポートが既に使用されている
別のアプリケーションがポート 9877 を使っている場合：
1. Blender の HS-MCP パネルでポート番号を変更（例: 9878）
2. `claude_desktop_config.json` の `BLENDER_PORT` も同じ番号に変更
3. 両方を再起動
—
## ポート割当表
| ポート | 用途 |
|——–|——|
| 9877 | BONSAI MCP（デフォルト） |
> 複数の Blender インスタンスを同時に使う場合は、それぞれ異なるポートを割り当ててください。
—
## FAQ
**Q: Blender 内蔵の Python ではダメ？**
A: ダメです。`hs_mcp_server.py` は Claude Desktop のプロセスとして起動されるため、System Python が必要です。Blender 内蔵 Python は Blender 側の addon（`server.py`）が使います。
**Q: BONSAI（BlenderBIM）アドオンは必須？**
A: `get_ifc_info` や IFC 関連機能を使う場合のみ必要です。シーン操作・コード実行だけなら BONSAI なしでも動作します。
**Q: Mac / Linux でも使える？**
A: 基本的に動作します。`claude_desktop_config.json` のパスが OS によって異なるので、Claude Desktop のドキュメントを参照してください。
**Q: Claude Desktop 以外（Cursor, Windsurf 等）で使える？**
A: MCP の stdio プロトコルをサポートするエディタであれば使用可能です。各エディタの MCP 設定に同じ `command` / `args` を指定してください。
—
## ライセンス
– **Blender アドオン**（`bonsai_mcp/`）: GPL（Blender アドオン規約に準拠）
– **外部 MCP サーバー**（`hs_mcp_server.py`）: HomeStructure LLC 独自ライセンス
—
*BONSAI MCP v0.1.1 — HomeStructure LLC*