# blender-mcp-bridge

Blender 公式 MCP アドオン（TCP port 9876）と Claude Desktop / Claude Code（stdio MCP）をつなぐブリッジ。

---

## 概要

### 開発動機

2026年6月現在、[Blender 公式 MCP アドオン](https://lab.blender.org/mcp) は独自の TCP プロトコル（`{"type": "execute", "code": "..."}`）を使っており、標準 MCP（JSON-RPC 2.0）を実装していないようだ。Claude Desktop は標準 MCP でしか動かないため、このブリッジを作成した。

### ゴール

標準 MCP クライアント（Claude Desktop / Claude Code / Gemini CLI 等）から Blender を直接操作できるようにする。

### 何ができるのか

Claude Code などの AI エージェントからの指示で、Blender のシーン操作（オブジェクト作成・変形・マテリアル設定）ができる様になる。

```
Claude Desktop / Claude Code
    │ stdio (MCP JSON-RPC 2.0)  ← Claude が話せる形式
    ▼
blender-mcp-bridge              ← このアプリ（変換・転送）
    │ TCP socket (port 9876)    ← Blender アドオンが受け付ける形式
    ▼
Blender アドオン
```

---

## 動作環境

### 前提条件

- Python 3.10 以上
- [Blender 公式 MCP アドオン](https://lab.blender.org/mcp)（Blender 側でインストール・有効化が必要）

### 対応プラットフォーム

macOS / Windows

---

## クイックスタート

### Claude Code から GitHub で直接インストール（推奨）

```bash
claude mcp add blender-mcp-bridge \
  --env BLENDER_HOST=localhost \
  --env BLENDER_PORT=9876 \
  -- uvx --from git+https://github.com/otinori/blender-mcp-bridge blender-mcp-bridge
```

`uvx` がリポジトリを直接取得して実行するため、clone や pip install は不要。

### セットアップスクリプトで登録する場合

```bash
# clone してから実行
git clone https://github.com/otinori/blender-mcp-bridge
cd blender-mcp-bridge
python3 scripts/setup.py  # MCP ライブラリのインストールと設定ファイルへの登録を一括実行
```

クライアントごとに個別設定する場合:

```bash
python3 scripts/setup_claude_desktop.py   # Claude Desktop
python3 scripts/setup_claude_code.py      # Claude Code (CLI)
python3 scripts/setup_gemini.py           # Gemini CLI
python3 scripts/setup_vscode.py           # VS Code（Continue / Copilot 等 MCP 対応拡張すべて）
python3 scripts/setup_codex.py            # OpenAI Codex CLI
```
※ 手元に環境がないため、、vscode版、codex版は動作確認できていません
---

## 主な使い方

1. **Blender MCP アドオン**を Blender にインストール・有効化する
2. **Blender を起動する**（アドオンが port 9876 でリッスン開始）
3. **Claude Desktop または Claude Code を再起動する**
4. Claude から「Blender のシーン情報を教えて」などと話しかける

接続先（ホスト/ポート）の変更は `BLENDER_HOST` / `BLENDER_PORT` 環境変数で行う。デフォルトは `localhost:9876`。

### ツール一覧

| ツール名 | 説明 |
|---|---|
| `blender_get_scene_info` | アクティブシーンの名前・オブジェクト数・フレーム情報を返す |
| `blender_list_objects` | シーン内オブジェクト一覧（`type` でフィルタ可） |
| `blender_get_object` | 指定オブジェクトの位置・回転・スケール・マテリアルを返す |
| `blender_create_object` | メッシュ・ライト・カメラ等を作成する |
| `blender_delete_object` | 指定オブジェクトを削除する |
| `blender_transform_object` | 位置・回転・スケールを変更する（部分更新可） |
| `blender_set_material` | Principled BSDF マテリアルをオブジェクトに設定する |
| `blender_execute_python` | 任意の Python コードを Blender 内で実行する |

---

## 構成

```
blender-mcp-bridge/
├── bridge.py          # MCP サーバ本体（変換・TCP 転送）
├── scripts/
│   ├── setup.py                 # 全クライアント一括セットアップ（対話メニュー）
│   ├── setup_claude_desktop.py  # Claude Desktop
│   ├── setup_claude_code.py     # Claude Code (CLI)
│   ├── setup_gemini.py          # Gemini CLI
│   ├── setup_vscode.py          # VS Code（MCP 対応拡張すべて）
│   └── setup_codex.py           # OpenAI Codex CLI
└── pyproject.toml
```
※ 手元に環境がないため、setup_vscode.pyとsetup_codex.pyの動作確認できていません

---

## ライセンス

Apache License 2.0 — [LICENSE](LICENSE) を参照。

プログラム開発の実験として、OpenSpecを試験導入しています。
そのため、`.claude/skills/openspec-*` および `.claude/commands/opsx/*` は OpenSpecのライセンスに基づきます。