Cinema4D MCP 서버

Cinema4D MCP — 모델 컨텍스트 프로토콜(MCP) 서버

Cinema4D MCP 서버는 Cinema 4D를 Claude에 연결하여 신속한 3D 조작을 가능하게 합니다.

구성 요소

C4D 플러그인 : MCP 서버로부터 명령을 수신하고 Cinema 4D 환경에서 이를 실행하는 소켓 서버입니다.
MCP 서버 : MCP 프로토콜을 구현하고 Cinema 4D 통합을 위한 도구를 제공하는 Python 서버입니다.

필수 조건

Cinema 4D(R2024+ 권장)
Python 3.10 이상(MCP 서버 구성 요소의 경우)

설치

프로젝트를 설치하려면 다음 단계를 따르세요.

저장소 복제

지엑스피1

MCP 서버 패키지 설치

pip install -e .

래퍼 스크립트를 실행 가능하게 만들기

chmod +x bin/cinema4d-mcp-wrapper

설정

Cinema 4D 플러그인 설정

Cinema 4D 플러그인을 설정하려면 다음 단계를 따르세요.

플러그인 파일 복사 : c4d_plugin/mcp_server_plugin.pyp 파일을 Cinema 4D 플러그인 폴더에 복사합니다. 경로는 운영 체제에 따라 다릅니다.
- macOS: /Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/
- Windows: C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\
소켓 서버 시작 :
- Cinema 4D를 엽니다.
- 확장 프로그램 > 소켓 서버 플러그인으로 이동하세요.
- 소켓 서버 컨트롤 대화 상자가 나타납니다. '서버 시작'을 클릭하세요.

클로드 데스크톱 구성

Claude Desktop을 구성하려면 구성 파일을 수정해야 합니다.

구성 파일을 엽니다 .
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- 또는 Claude Desktop의 설정 메뉴(설정 > 개발자 > 구성 편집)를 사용하세요.
MCP 서버 구성 추가 : 개발/미공개 서버의 경우 다음 구성을 추가합니다.
"mcpServers": { "cinema4d": { "command": "python3", "args": ["/Users/username/cinema4d-mcp/main.py"] } }
구성 파일을 업데이트한 후 Claude Desktop을 다시 시작합니다 .

{
  "mcpServers": {
    "cinema4d": {
      "command": "cinema4d-mcp-wrapper",
      "args": []
    }
  }
}

용법

Cinema 4D 소켓 서버가 실행 중인지 확인하세요.
Claude Desktop을 열고 입력 상자에서 망치 아이콘 🔨을 찾으세요. 이는 MCP 도구를 사용할 수 있음을 나타냅니다.
Claude를 통해 Cinema 4D와 상호 작용하려면 사용 가능한 도구 명령을 사용하세요.

테스트

명령줄 테스트

명령줄에서 직접 Cinema 4D 소켓 서버를 테스트하려면:

python main.py

서버가 성공적으로 시작되고 Cinema 4D에 연결되었다는 확인 메시지가 표시됩니다.

MCP 테스트 하네스로 테스트

저장소에는 미리 정의된 명령 시퀀스를 실행하기 위한 간단한 테스트 하네스가 포함되어 있습니다.

테스트 명령 파일 ( tests/mcp_test_harness.jsonl ): JSONL 형식의 명령 시퀀스를 포함하고 있으며, 순서대로 실행할 수 있습니다. 각 줄은 매개변수가 포함된 단일 MCP 명령을 나타냅니다.
GUI 테스트 러너 ( tests/mcp_test_harness_gui.py ): 테스트 명령을 실행하기 위한 간단한 Tkinter GUI:
python tests/mcp_test_harness_gui.py
GUI를 사용하면 다음을 수행할 수 있습니다.
- JSONL 테스트 파일을 선택하세요
- 명령을 순서대로 실행하세요
- Cinema 4D의 응답을 확인하세요

이 테스트 하네스는 특히 다음과 같은 경우에 유용합니다.

새로운 명령을 빠르게 테스트
업데이트 후 플러그인 기능 확인
디버깅을 위한 복잡한 장면 재생성
다양한 Cinema 4D 버전 간 호환성 테스트

문제 해결 및 디버깅

로그 파일을 확인하세요.
tail -f ~/Library/Logs/Claude/mcp*.log
Claude Desktop을 연 후 Cinema 4D 콘솔에 연결이 표시되는지 확인하세요.
래퍼 스크립트를 직접 테스트하세요.
cinema4d-mcp-wrapper
mcp 모듈을 찾는 데 오류가 있는 경우 시스템 전체에 설치하세요.
pip install mcp
고급 디버깅을 위해 MCP Inspector를 사용하세요.
npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp

프로젝트 파일 구조

cinema4d-mcp/
├── .gitignore
├── LICENSE
├── README.md
├── main.py
├── pyproject.toml
├── setup.py
├── bin/
│   └── cinema4d-mcp-wrapper
├── c4d_plugin/
│   └── mcp_server_plugin.pyp
├── src/
│   └── cinema4d_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── config.py
│       └── utils.py
└── tests/
    ├── test_server.py
    ├── mcp_test_harness.jsonl
    └── mcp_test_harness_gui.py

도구 명령

일반 장면 및 실행

get_scene_info : 활성 Cinema 4D 장면에 대한 요약 정보를 가져옵니다. ✅
list_objects : 모든 장면 객체를 계층 구조와 함께 나열합니다. ✅
group_objects : 선택한 객체를 새 null로 그룹화합니다. ✅
execute_python : Cinema 4D 내에서 사용자 정의 Python 코드를 실행합니다. ✅
save_scene : 현재 Cinema 4D 프로젝트를 디스크에 저장합니다. ✅
load_scene : .c4d 파일을 장면에 로드합니다. ✅
set_keyframe : 객체 속성(위치, 회전 등)에 키프레임을 설정합니다. ✅

객체 생성 및 수정

add_primitive : 장면에 기본형(큐브, 구, 원뿔 등)을 추가합니다. ✅
modify_object : 기존 객체의 변형이나 속성을 수정합니다. ✅
create_abstract_shape : 유기적이고 비표준적인 추상 형태를 만듭니다. ✅

카메라 및 애니메이션

create_camera : 장면에 새로운 카메라를 추가합니다. ✅
animate_camera : 경로(선형 또는 스플라인 기반)를 따라 카메라를 애니메이션화합니다. ✅

조명 및 재료

create_light : 장면에 조명(옴니, 스팟 등)을 추가합니다. ✅
create_material : 표준 Cinema 4D 소재를 생성합니다. ✅
apply_material : 대상 객체에 재질을 적용합니다. ✅
apply_shader : 양식화된 셰이더나 절차적 셰이더를 생성하고 적용합니다. ✅

Redshift 지원

validate_redshift_materials : Redshift 머티리얼 설정 및 연결을 확인합니다. ✅ ⚠️ (Redshift 머티리얼이 완전히 구현되지 않았습니다)

모그래프 & 필드

create_mograph_cloner : MoGraph 클로너(선형, 방사형, 격자형 등)를 추가합니다. ✅
add_effector : MoGraph 이펙터(랜덤, 일반 등)를 추가합니다. ✅
apply_mograph_fields : MoGraph 필드를 객체에 추가하고 연결합니다. ✅

역학 및 물리학

create_soft_body : 객체에 소프트 바디 태그를 추가합니다. ✅
apply_dynamics : 강체 또는 연체 물리를 적용합니다. ✅

렌더링 및 미리보기

render_frame : 프레임을 렌더링하여 디스크에 저장합니다(파일 기반 출력만 해당). ⚠️ (작동하지만 MemoryError: Bitmap Init 실패로 인해 고해상도에서는 실패합니다. 이는 리소스 제한입니다.)
render_preview : 빠른 미리보기를 렌더링하고 base64 이미지를 반환합니다(AI용). ✅
snapshot_scene : 장면(객체 + 미리보기 이미지)의 스냅샷을 캡처합니다. ✅

호환성 계획 및 로드맵

시네마 4D 버전	파이썬 버전	호환성 상태	노트
R21 / S22	파이썬 2.7	❌ 지원되지 않음	레거시 API와 Python 버전이 너무 오래되었습니다.
R23	파이썬 3.7	🔍 계획되지 않음	현재 테스트되지 않음
S24 / R25 / S26	파이썬 3.9	⚠️ 가능 (미정)	누락된 API에 대한 테스트 및 대체가 필요합니다.
2023.0 / 2023.1	파이썬 3.9	🧪 진행 중	핵심 기능에 대한 폴백 지원 타겟팅
2023.2	파이썬 3.10	🧪 진행 중	계획된 테스트 기반과 일치합니다.
2024.0	파이썬 3.11	✅ 지원됨	확인됨
2025.0+	파이썬 3.11	✅ 완벽히 지원됨	주요 개발 목표

호환성 목표

단기 : C4D 2023.1+(Python 3.9 및 3.10)와의 호환성 보장
중간 기한 : 누락된 MoGraph 및 Field API에 대한 조건 처리 추가
장기 : 수요가 발생할 경우 R23–S26 지원을 위한 선택적 레거시 플러그인 모듈을 고려하세요.

최근 수정 사항

컨텍스트 인식: GUID를 사용하여 강력한 객체 추적을 구현했습니다. 객체를 생성하는 명령은 컨텍스트(GUID, actual_name 등)를 반환합니다. 이후 명령은 테스트 하네스/서버에서 전달된 GUID를 올바르게 사용하여 객체를 안정적으로 찾습니다.
객체 찾기: GUID(숫자 문자열 형식)를 올바르게 처리하기 위해 find_object_by_name을 다시 작업하고, 재귀 오류를 수정했으며, doc.SearchObject가 실패할 때 안정성을 개선했습니다.
GUID 감지: 명령 처리기(apply_material, create_mograph_cloner, add_effector, apply_mograph_fields, set_keyframe, group_objects)는 이제 다양한 매개변수(object_name, target, target_name, 목록 항목)에 전달된 식별자가 GUID인지 여부를 올바르게 감지하고 그에 따라 검색합니다.
create_mograph_cloner: getattr 폴백을 사용하여 MoGraph 매개변수(예: MG_LINEAR_PERSTEP)가 누락되어 발생하는 AttributeError를 수정했습니다. 발견된 객체가 복제를 위해 올바르게 전달되지 않는 로직 버그를 수정했습니다.
렌더링: doc.ExecutePasses 관련 render_frame의 TypeError가 수정되었습니다. snapshot_scene이 이제 제대로 작동하는 base64 렌더링 로직을 사용합니다. 큰 render_frame은 여전히 메모리 제한을 받습니다.
등록: c4d.NilGuid에 대한 AttributeError가 수정되었습니다.

Cinema4D MCP Server

Integrations