Blender MCP

Claude AIがMCP(Model Context Protocol)を通じてBlender 3Dを直接制御するためのツールです。

自然言語で命令すると、ClaudeがBlenderシーン内でオブジェクトの作成、修正、削除、Pythonコードの実行を自動的に行います。

動作方式

Claude Desktop
     │ MCP (stdio / HTTP·SSE)
     ▼
MCP Server (Python)          ← 이 저장소
     │ TCP Socket :9999
     ▼
Blender Add-on (Python)      ← 이 저장소
     │ bpy API
     ▼
Blender 씬

Related MCP server: BlenderMCP

要件

インストール方法

ステップ1 — リポジトリのクローン

git clone https://github.com/nowcika/blender_mcp.git
cd blender_mcp

ステップ2 — MCPサーバーの依存関係のインストール

pip install -r requirements.txt

requirements.txt の内容: mcp>=1.0.0

ステップ3 — Blenderアドオンのインストール

まず、addon/ フォルダーをzipファイルに圧縮します:

# 터미널에서 프로젝트 루트 위치에서 실행
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

次に、Blenderにインストールします:

1. Blender画面上部のメニューから 編集(Edit) をクリック

2. 環境設定(Preferences) をクリック

3. 環境設定ウィンドウの左側から アドオン(Add-ons) をクリック

4. 右上の ドロップダウン矢印(⌄) → ディスクからインストール(Install from Disk) をクリック

5. 作成した blender_mcp_addon.zip ファイルを選択

6. アドオンをインストール(Install Add-on) ボタンをクリック

7. リストに表示された "Blender MCP" 項目の左側のチェックボックスをクリックして有効化

ステップ4 — Blenderでソケットサーバーを開始

3Dビューポートとは？ Blenderを開くと中央に見える大きな3D空間のことです。オブジェクトを配置・操作するメインの作業画面です。 サイドバーとは？ 3Dビューポート内でキーボードの N キーを押すと右側に開くパネルのことです。これがサイドバーです。

1. Blender中央の 3Dビューポート 領域の上にマウスカーソルを置く

2. キーボードの N キーを押す → 右側にサイドバーパネルが開く

3. サイドバー上部のタブから MCP タブをクリック

4. Start MCP Server ボタンをクリック

5. ボタンの上のステータス表示が Running に変われば準備完了

Nキーが反応しない場合: マウスカーソルが3Dビューポート内にあるか確認してください。Blenderはマウスの位置によってショートカットキーの対象が変わります。

デフォルトポート: 9999。変更する場合は環境変数を設定してください:

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Claude Desktop連携 (stdio — 推奨)

claude_desktop_config.json ファイルに以下の内容を追加します。

ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "python3",
      "args": ["-m", "server", "--transport", "stdio"],
      "cwd": "/절대경로/blender_mcp"
    }
  }
}

/絶対パス/blender_mcp を実際のクローンパスに変更してください。 Windowsの例: "cwd": "C:\\Users\\yourname\\blender_mcp"

設定後、Claude Desktopを再起動します。

Claude Code (ターミナルCLI) 連携

Claude Desktopの代わりにターミナルで claude コマンドを使用する場合です。

方法1 — プロジェクトフォルダーで自動認識 (推奨)

このリポジトリには .mcp.json ファイルが含まれています。 blender_mcp フォルダー内で claude を実行すると、自動的にMCPサーバーが登録されます。

cd blender_mcp
claude        # .mcp.json을 자동으로 읽어서 blender MCP 활성화

方法2 — どこからでも使用できるようにグローバル登録

/絶対パス/blender_mcp を実際のパスに置き換えてターミナルに入力してください:

claude mcp add --scope user blender python3 /절대경로/blender_mcp/start_server.py

例 (Windows):

claude mcp add --scope user blender python3 C:/Users/yourname/blender_mcp/start_server.py

登録の確認:

claude mcp list

HTTP/SSEモード (リモート接続)

ローカルではなくリモートサーバー上のBlenderを制御する場合に使用します。

# MCP 서버를 HTTP 모드로 실행
python3 -m server --transport http --host 0.0.0.0 --port 8080

Claude Desktopの設定:

{
  "mcpServers": {
    "blender": {
      "url": "http://서버IP:8080/sse"
    }
  }
}

使用可能なMCPツール

Claudeとの対話時に以下のツールが自動的に有効になります。

使用例

Claude Desktopのチャット欄で:

큐브 하나 만들어줘
→ Claude가 create_object 도구 호출 → Blender에 Cube 생성

방금 만든 큐브를 (3, 0, 1)로 이동하고 45도 회전해줘
→ Claude가 modify_object 호출 → 위치·회전 적용

현재 씬에 있는 모든 오브젝트 목록 알려줘
→ Claude가 get_scene_info 호출 → 오브젝트 목록 반환

環境変数の設定

トラブルシューティング

"Blender is not running" エラー

• Blenderが起動しているか確認してください

• 3Dビューポートで Nキー → MCPタブ → Start MCP Server ボタンを押したか確認してください

• ファイアウォールがポート9999をブロックしていないか確認してください

アドオンがリストに表示されない場合

• Blenderのバージョンが4.2以上か確認してください (画面上部の ヘルプ(Help) → Blenderについて(About Blender) で確認)

• addon/ フォルダー内のファイルがzipのルートに直接ある必要があります。以下の方法で再圧縮してください:

# 올바른 압축 방법 (addon/ 폴더 안에서 실행)
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

MCPサーバーに接続できない場合

# 의존성 확인
pip show mcp

# 서버 직접 테스트 (stdio 대신 로그 확인용)
python3 -m server --transport http --port 8080
# http://localhost:8080/sse 접근해서 응답 확인

プロジェクト構造

blender_mcp/
├── addon/
│   ├── __init__.py           # Blender Add-on + 소켓 서버
│   ├── executor.py           # bpy 명령 실행기
│   └── blender_manifest.toml # Blender 5.x Extension 매니페스트
├── server/
│   ├── __init__.py           # MCP 서버 진입점 (stdio / HTTP)
│   ├── tools.py              # MCP 도구 6개 정의
│   └── blender_client.py     # Blender 소켓 클라이언트
├── requirements.txt
└── README.md

ライセンス

GPL-3.0-or-later