Skip to main content
Glama
deenesjakoruzh
parkspark

blender-control-mcp

by parkspark
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

blender-control-mcp

blender-control-mcp는 Blender를 로컬 Windows의 background 모드에서 안전하게 제어하는 독립형 STDIO MCP 서버입니다. LLM, 자연어 해석, 임의 Python/셸 실행 기능은 포함하지 않습니다. 서버가 공개하는 7개의 구조화 도구만 사용할 수 있으며, 호스트와 Blender 내부에서 입력을 각각 검증합니다.

요구 환경

  • Windows

  • Python 3.12 이상

  • Blender 5.2 LTS 권장

  • 기본 Blender 경로: C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe

Related MCP server: blend-ai

설치

프로젝트 루트에서 PowerShell로 실행합니다.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Blender가 다른 위치에 있으면 환경 변수를 설정합니다.

$env:BLENDER_EXECUTABLE = "D:\Apps\Blender\blender.exe"

선택 환경 변수:

  • BLENDER_EXECUTABLE: blender.exe 경로

  • BLENDER_TIMEOUT_SECONDS: 한 작업의 timeout, 1~3600초, 기본 180초

  • BLENDER_CONTROL_WORKDIR: 읽기 전용 검사 작업의 로그/계획 저장 루트. 기본값은 %TEMP%\blender-control-mcp

서버 실행

.\.venv\Scripts\blender-control-mcp.exe

또는 다음과 같이 실행할 수 있습니다.

.\.venv\Scripts\python.exe -m blender_control_mcp.server

STDIO 서버이므로 정상 실행 시 대화형 프롬프트나 일반 로그를 stdout에 출력하지 않습니다. MCP 클라이언트가 프로세스를 시작하고 JSON-RPC를 주고받습니다.

Codex 연결

Codex는 로컬 STDIO MCP 서버를 지원하며 사용자 ~/.codex/config.toml 또는 신뢰한 프로젝트의 .codex/config.toml에 설정할 수 있습니다. 아래 경로는 이 저장소의 기본 위치를 사용한 예시입니다.

[mcp_servers.blender_control]
command = "C:/Users/park/Desktop/dev_tool/blender-control-mcp/.venv/Scripts/python.exe"
args = ["-m", "blender_control_mcp.server"]
cwd = "C:/Users/park/Desktop/dev_tool/blender-control-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
default_tools_approval_mode = "writes"

[mcp_servers.blender_control.env]
BLENDER_EXECUTABLE = "C:/Users/park/Applications/blender-5.2.0-windows-x64/blender.exe"
BLENDER_TIMEOUT_SECONDS = "180"

설정 후 Codex를 재시작하고 /mcp 또는 codex mcp list로 연결 상태를 확인합니다. UI에서는 Settings → MCP servers → Add server → STDIO를 선택해 같은 command/args를 입력할 수도 있습니다. 최신 설정 항목은 OpenAI의 Codex MCP 문서를 참고하세요.

CLI로 추가하는 예시는 다음과 같습니다.

codex mcp add blender_control --env BLENDER_EXECUTABLE=C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe -- C:\Users\park\Desktop\dev_tool\blender-control-mcp\.venv\Scripts\python.exe -m blender_control_mcp.server

다른 MCP 클라이언트 연결

STDIO 서버 설정 형식이 JSON인 클라이언트의 일반적인 예시입니다. 실제 설정 파일 위치와 키 이름은 클라이언트 문서를 확인하세요.

{
  "mcpServers": {
    "blender-control": {
      "command": "C:\\Users\\park\\Desktop\\dev_tool\\blender-control-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "blender_control_mcp.server"],
      "env": {
        "BLENDER_EXECUTABLE": "C:\\Users\\park\\Applications\\blender-5.2.0-windows-x64\\blender.exe"
      }
    }
  }
}

도구

모든 경로 입력은 문자열입니다. 입력 자산은 .glb, .blend, .fbx만 허용합니다. target은 all 또는 대소문자를 포함해 정확히 일치하는 이름이어야 합니다. 찾지 못하거나 모호하면 서버는 임의 선택하지 않고 target_not_found/ambiguous_target 오류와 후보 목록을 반환합니다.

scene.inspect

입력:

{"input_path":"C:\\assets\\chair.glb"}

data.objects에 이름, 타입, 재질 슬롯, 메시 정점/폴리곤 수, dimensions, location, Modifier 목록을 반환합니다.

{
  "success": true,
  "data": {
    "object_count": 1,
    "objects": [{
      "name": "Chair",
      "type": "MESH",
      "material_slots": ["Wood"],
      "vertex_count": 1200,
      "polygon_count": 800,
      "dimensions": [1.0, 1.1, 1.8],
      "location": [0.0, 0.0, 0.0],
      "modifiers": []
    }]
  }
}

material.list

입력:

{"input_path":"C:\\assets\\chair.blend"}

반환 예시:

{
  "success": true,
  "data": {
    "material_count": 1,
    "materials": [{
      "name": "Wood",
      "base_color": [0.4, 0.2, 0.1, 1.0],
      "roughness": 0.55,
      "metallic": 0.0,
      "alpha": 1.0,
      "base_color_texture_linked": true
    }]
  }
}

asset.apply_material

base_color는 01 범위 RGB 또는 RGBA이며 roughness, metallic, alpha도 01입니다. 하나 이상의 변경값이 필요합니다.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Wood",
  "base_color":[0.1,0.3,0.8,0.75],
  "roughness":0.25,
  "alpha":0.75
}

정확한 재질 이름 또는 재질이 하나뿐인 오브젝트 이름을 대상으로 삼습니다. 수정된 GLB, BLEND, FBX를 모두 생성합니다. 한 오브젝트에 재질이 여러 개면 재질 후보를 반환하고 명시적 선택을 요구합니다.

asset.transform

각 벡터는 숫자 3개입니다. scale은 각 축 0.001~1000이고, 한 가지 이상의 변경값이 필요합니다.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "location":[0,0,1],
  "rotation_degrees":[0,0,90],
  "scale":[1.2,1.2,1.2]
}

수정된 GLB, BLEND, FBX를 모두 생성합니다.

asset.add_modifier

Bevel 입력 예시:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"bevel",
  "width":0.03,
  "segments":3
}

Decimate 입력 예시:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"decimate",
  "ratio":0.5
}

Bevel은 width > 01000, segments 116만 허용합니다(기본 0.1/3). Decimate는 ratio 0.01~1만 허용합니다(기본 0.5). 다른 Modifier나 서로 섞인 파라미터는 거부합니다. 수정된 세 형식을 모두 생성합니다.

asset.set_smooth_shading

{
  "input_path":"C:\\assets\\chair.fbx",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair"
}

대상 메시 폴리곤에 smooth shading을 설정하고 수정된 GLB, BLEND, FBX를 모두 생성합니다.

asset.export

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\exports",
  "formats":["glb","blend","fbx"]
}

formats는 glb, blend, fbx 중 중복 없는 하나 이상이어야 하며 요청된 형식만 생성합니다.

공통 응답과 산출물

모든 호출은 구조화된 응답을 반환합니다. 수정/내보내기 도구는 <output_directory>/<operation_id>/에 산출물을 만들고, 읽기 도구는 임시 작업 루트 아래에 로그를 남깁니다.

{
  "success": true,
  "operation_id": "9bc12a7f57f24f8ba9d9af2f78de3041",
  "operation": "asset.export",
  "artifacts": [
    "C:\\assets\\exports\\9bc12a7f57f24f8ba9d9af2f78de3041\\chair.glb"
  ],
  "summary": "asset.export completed successfully",
  "data": {"formats":["glb"],"artifact_count":1},
  "operation_path": "...\\operation.json",
  "log_path": "...\\blender.log",
  "log_excerpt": "Blender 5.2.0 ...",
  "command": ["...\\blender.exe","--background","..."],
  "exit_code": 0,
  "errors": []
}

실패 시에도 가능한 경우 operation.json과 blender.log를 남기며 다음처럼 오류 코드와 후보를 반환합니다.

{
  "success": false,
  "summary": "object target 'Seat' was not found",
  "artifacts": [],
  "errors": [{
    "code": "target_not_found",
    "message": "object target 'Seat' was not found",
    "candidates": ["Chair", "Table"]
  }]
}

테스트

전체 테스트:

.\.venv\Scripts\python.exe -m pytest -q

Blender 없는 환경에서는 실제 Blender 통합 테스트 하나만 자동으로 skip되고 단위 테스트는 통과합니다.

# 빠른 단위 테스트만
.\.venv\Scripts\python.exe -m pytest -m "not integration" -q

# 실제 Blender 통합 테스트만
.\.venv\Scripts\python.exe -m pytest -m integration -q

통합 테스트는 작은 GLB를 만든 뒤 씬 검사, 재질 색상/거칠기/투명도 변경, scale 변경, Bevel 추가, GLB/BLEND/FBX 생성을 실제 Blender에서 검증합니다.

보안 설계

  • 임의 Blender Python, Python 문자열, 자연어 계획, 셸 명령을 받는 도구가 없습니다.

  • 브리지는 고정된 blender_mcp_bridge.py 하나이며 JSON operation type/필드/값을 allow-list로 재검증합니다.

  • 브리지에 eval, exec, subprocess, 외부 명령 실행이 없습니다.

  • Blender는 --background --factory-startup --disable-autoexec로 실행됩니다.

  • subprocess.run(..., shell=False)와 인자 배열을 사용하며 timeout을 적용합니다.

  • 입력 파일은 존재 여부와 확장자를 Blender 실행 전에 검증합니다.

  • 출력은 무작위 operation ID 하위 폴더에만 기록하고 기존 산출물과 원본을 덮어쓰지 않습니다.

  • 브리지는 계획, 결과, 산출물이 모두 같은 작업 폴더 경계 안에 있는지 다시 확인합니다.

MVP 제한 사항

  • 이미지 텍스처 픽셀 수정, Texture Paint, 베이크는 지원하지 않습니다.

  • Base Color 소켓에 텍스처/노드가 연결된 재질은 기본값을 바꿔도 최종 외관이 바뀌지 않을 수 있습니다. 이 경우 blender.log에 경고를 남깁니다.

  • 재질 변경은 Principled BSDF가 있는 재질만 지원합니다.

  • Modifier는 Bevel과 Decimate만 추가하며 적용(apply)하지는 않습니다. 내보내기 형식의 exporter가 평가된 결과를 처리하는 방식은 Blender 형식별 동작을 따릅니다.

  • Blender 파일 자체의 손상, Blender importer/exporter 오류, 포맷 간 기능 차이는 구조화된 오류와 로그로 보고하지만 자동 복구하지 않습니다.

  • 각 도구 호출은 별도의 Blender 프로세스를 시작하므로 큰 자산에서는 시작·변환 비용이 큽니다.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

  • blend-ai

    HoldMyBeer-gg
    A
    license
    B
    quality
    B
    maintenance
    An MCP server that enables AI assistants to control Blender through 108 specialized tools for 3D modeling, animation, and rendering. It provides a secure, thread-safe interface to execute validated operations in Blender using natural language commands.
    100
    126
    AGPL 3.0

  • Blender MCP

    YellowFoxH4XOR
    F
    license
    A
    quality
    C
    maintenance
    A headless-first Model Context Protocol server for safe, deterministic Blender automation, exposing typed tools to inspect scenes and render previews without arbitrary command execution.
    3

  • blender-lab-mcp-client

    A-to-PC
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Blender that connects to the official Blender Lab add-on, exposing 27 tools for scene manipulation, object editing, materials, rendering, and Python execution through the add-on's actual wire protocol.
    MIT

View all related MCP servers

Related MCP Connectors

  • ChiR24-unreal_mcp

    Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…

  • MCP Fortress

    Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.

  • ChiR24-unreal_mcp_server

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/parkspark/blender-control-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server