Blender MCP

A tool that allows Claude AI to directly control Blender 3D via the MCP (Model Context Protocol).

By giving commands in natural language, Claude automatically performs object creation, modification, deletion, and Python code execution in the Blender scene.

How it works

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

Related MCP server: BlenderMCP

Requirements

Installation

Step 1 — Clone the repository

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

Step 2 — Install MCP server dependencies

pip install -r requirements.txt

requirements.txt content: mcp>=1.0.0

Step 3 — Install the Blender add-on

First, compress the addon/ folder into a zip file:

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

Now, install it in Blender:

1. Click Edit in the top menu of the Blender screen

2. Click Preferences

3. Click Add-ons on the left side of the Preferences window

4. Click the dropdown arrow (⌄) in the top right → Install from Disk

5. Select the blender_mcp_addon.zip file you just created

6. Click the Install Add-on button

7. Enable it by clicking the checkbox to the left of the "Blender MCP" item that appears in the list

Step 4 — Start the socket server in Blender

What is the 3D Viewport? When you open Blender, you see a large 3D space in the center. This is the main workspace where you place and manipulate objects. What is the Sidebar? Press the N key on your keyboard inside the 3D Viewport to open the panel on the right. This is the sidebar.

1. Place your mouse cursor over the 3D Viewport area in the center of Blender

2. Press the N key on your keyboard → The sidebar panel will open on the right

3. Click the MCP tab among the tabs at the top of the sidebar

4. Click the Start MCP Server button

5. Once the status display above the button changes to Running, it is ready

If the N key doesn't work: Make sure your mouse cursor is inside the 3D Viewport. Blender's shortcuts depend on the mouse position.

Default port: 9999. To change it, set the environment variable:

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Claude Desktop Integration (stdio — Recommended)

Add the following content to your claude_desktop_config.json file.

File location:

• 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"
    }
  }
}

Change /absolute/path/to/blender_mcp to your actual clone path. Windows example: "cwd": "C:\\Users\\yourname\\blender_mcp"

After configuring, restart Claude Desktop.

Claude Code (Terminal CLI) Integration

This is for when you use the claude command in the terminal instead of Claude Desktop.

Method 1 — Automatic detection in the project folder (Recommended)

This repository includes a .mcp.json file. If you run claude inside the blender_mcp folder, the MCP server is registered automatically.

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

Method 2 — Global registration for use anywhere

Replace /absolute/path/to/blender_mcp with the actual path and enter it into the terminal:

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

Example (Windows):

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

Verify registration:

claude mcp list

HTTP/SSE Mode (Remote Access)

Use this when controlling Blender from a remote server rather than locally.

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

Claude Desktop configuration:

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

Available MCP Tools

The following tools are automatically enabled when chatting with Claude.

Usage Example

In the Claude Desktop chat window:

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

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

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

Environment Variable Settings

Troubleshooting

"Blender is not running" error

• Check if Blender is running

• Check if you pressed the Start MCP Server button in the MCP tab (via N key) in the 3D Viewport

• Check if the firewall is blocking port 9999

Add-on does not appear in the list

• Check if your Blender version is 4.2 or higher (check via Help → About Blender at the top of the screen)

• The files inside the addon/ folder must be directly at the root of the zip. Compress them again using the following method:

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

MCP server fails to connect

# 의존성 확인
pip show mcp

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

Project Structure

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

License

GPL-3.0-or-later