Blender MCP

Una herramienta que permite a Claude AI controlar Blender 3D directamente a través del MCP (Model Context Protocol).

Al dar instrucciones en lenguaje natural, Claude realiza automáticamente la creación, modificación, eliminación de objetos y la ejecución de código Python en la escena de Blender.

Cómo funciona

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

Related MCP server: BlenderMCP

Requisitos

Método de instalación

Paso 1 — Clonar el repositorio

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

Paso 2 — Instalar dependencias del servidor MCP

pip install -r requirements.txt

Contenido de requirements.txt: mcp>=1.0.0

Paso 3 — Instalar el complemento (Add-on) de Blender

Primero, comprima la carpeta addon/ en un archivo zip:

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

Ahora, instálelo en Blender:

1. Haga clic en Editar (Edit) en el menú superior de la pantalla de Blender.

2. Haga clic en Preferencias (Preferences).

3. Haga clic en Complementos (Add-ons) en el lado izquierdo de la ventana de preferencias.

4. Haga clic en la flecha desplegable (⌄) en la parte superior derecha → Instalar desde disco (Install from Disk).

5. Seleccione el archivo blender_mcp_addon.zip que acaba de crear.

6. Haga clic en el botón Instalar complemento (Install Add-on).

7. Active el elemento "Blender MCP" que aparece en la lista marcando la casilla de verificación a su izquierda.

Paso 4 — Iniciar el servidor de socket en Blender

¿Qué es el visor 3D (3D Viewport)? Al abrir Blender, verá un gran espacio 3D en el centro. Es la pantalla de trabajo principal donde se colocan y manipulan los objetos. ¿Qué es la barra lateral (Sidebar)? Si presiona la tecla N en el teclado dentro del visor 3D, se abrirá un panel a la derecha. Esa es la barra lateral.

1. Coloque el cursor del ratón sobre el área del visor 3D en el centro de Blender.

2. Presione la tecla N del teclado → Se abrirá el panel de la barra lateral a la derecha.

3. Haga clic en la pestaña MCP entre las pestañas superiores de la barra lateral.

4. Haga clic en el botón Start MCP Server.

5. Cuando el indicador de estado sobre el botón cambie a Running, estará listo.

Si la tecla N no funciona: Asegúrese de que el cursor del ratón esté dentro del visor 3D. Blender cambia los atajos de teclado según la posición del ratón.

Puerto predeterminado: 9999. Para cambiarlo, configure la variable de entorno:

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Integración con Claude Desktop (stdio — recomendado)

Agregue el siguiente contenido al archivo claude_desktop_config.json.

Ubicación del archivo:

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

Cambie /ruta/absoluta/blender_mcp por la ruta real de clonación. Ejemplo en Windows: "cwd": "C:\\Users\\yourname\\blender_mcp"

Después de configurar, reinicie Claude Desktop.

Integración con Claude Code (CLI de terminal)

Para casos en los que utiliza el comando claude en la terminal en lugar de Claude Desktop.

Método 1 — Reconocimiento automático en la carpeta del proyecto (recomendado)

Este repositorio incluye un archivo .mcp.json. Si ejecuta claude dentro de la carpeta blender_mcp, el servidor MCP se registrará automáticamente.

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

Método 2 — Registro global para usar en cualquier lugar

Cambie /ruta/absoluta/blender_mcp por la ruta real e ingrese en la terminal:

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

Ejemplo (Windows):

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

Verificar registro:

claude mcp list

Modo HTTP/SSE (conexión remota)

Se utiliza para controlar Blender desde un servidor remoto, no local.

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

Configuración de Claude Desktop:

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

Herramientas MCP disponibles

Las siguientes herramientas se activan automáticamente al chatear con Claude.

Ejemplo de uso

En la ventana de chat de Claude Desktop:

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

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

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

Configuración de variables de entorno

Solución de problemas

Error "Blender is not running"

• Verifique si Blender se está ejecutando.

• Asegúrese de haber presionado el botón N → Pestaña MCP → Start MCP Server en el visor 3D.

• Verifique que el firewall no esté bloqueando el puerto 9999.

Cuando el complemento no aparece en la lista

• Verifique que la versión de Blender sea 4.2 o superior (verifique en Ayuda (Help) → Acerca de Blender (About Blender) en la parte superior de la pantalla).

• Los archivos dentro de la carpeta addon/ deben estar directamente en la raíz del zip. Comprima nuevamente usando el siguiente método:

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

Cuando el servidor MCP no se conecta

# 의존성 확인
pip show mcp

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

Estructura del proyecto

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

Licencia

GPL-3.0-or-later