Cinema4D MCP Server

Cinema4D MCP: Servidor de Protocolo de Contexto de Modelo (MCP)

El servidor MCP de Cinema4D conecta Cinema 4D con Claude, lo que permite una manipulación 3D asistida por indicaciones.

Tabla de contenido

• Componentes
• Prerrequisitos
• Instalación
• Configuración
• Uso
• Desarrollo
• Solución de problemas y depuración
• Estructura de archivos
• Comandos de herramientas

Componentes

1. Complemento C4D : un servidor de socket que escucha los comandos del servidor MCP y los ejecuta en el entorno de Cinema 4D.
2. Servidor MCP : un servidor Python que implementa el protocolo MCP y proporciona herramientas para la integración de Cinema 4D.

Prerrequisitos

• Cinema 4D (se recomienda R2024+)
• Python 3.10 o superior (para el componente del servidor MCP)

Instalación

Para instalar el proyecto, siga estos pasos:

Clonar el repositorio

Instalar el paquete del servidor MCP

Hacer que el script wrapper sea ejecutable

Configuración

Configuración del complemento Cinema 4D

Para configurar el complemento Cinema 4D, siga estos pasos:

1. Copiar el archivo del plugin : Copiar el archivo c4d_plugin/mcp_server_plugin.pyp a la carpeta de plugins de Cinema 4D. La ruta varía según el sistema operativo:
   • macOS: /Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/
   • Windows: C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\
2. Iniciar el servidor de sockets :
   • Cine 4D abierto.
   • Vaya a Extensiones > Complemento de servidor de sockets
   • Debería aparecer una ventana de diálogo de control del servidor de sockets. Haga clic en "Iniciar servidor".

Configuración del escritorio de Claude

Para configurar Claude Desktop, es necesario modificar su archivo de configuración:

1. Abra el archivo de configuración :
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json
   • Alternativamente, utilice el menú Configuración en Claude Desktop (Configuración > Desarrollador > Editar configuración).
2. Agregar configuración de servidor MCP : para servidores de desarrollo/no publicados, agregue la siguiente configuración:
   "mcpServers": { "cinema4d": { "command": "python3", "args": ["/Users/username/cinema4d-mcp/main.py"] } }
3. Reinicie Claude Desktop después de actualizar el archivo de configuración.

Uso

1. Asegúrese de que el servidor de sockets de Cinema 4D esté ejecutándose.
2. Abra Claude Desktop y busque el ícono del martillo 🔨 en el cuadro de entrada, que indica que las herramientas MCP están disponibles.
3. Utilice los comandos de herramientas disponibles para interactuar con Cinema 4D a través de Claude.

Pruebas

Pruebas de línea de comandos

Para probar el servidor de sockets de Cinema 4D directamente desde la línea de comandos:

Debería ver un resultado que confirme el inicio exitoso del servidor y la conexión a Cinema 4D.

Pruebas con el arnés de prueba MCP

El repositorio incluye un arnés de prueba simple para ejecutar secuencias de comandos predefinidas:

1. Archivo de comandos de prueba ( tests/mcp_test_harness.jsonl ): Contiene una secuencia de comandos en formato JSONL que se pueden ejecutar en orden. Cada línea representa un comando MCP con sus parámetros.
2. Ejecutor de pruebas GUI ( tests/mcp_test_harness_gui.py ): una GUI Tkinter simple para ejecutar los comandos de prueba:
   python tests/mcp_test_harness_gui.py
   La GUI le permite:
   • Seleccione un archivo de prueba JSONL
   • Ejecute los comandos en secuencia
   • Ver las respuestas de Cinema 4D

Este arnés de prueba es particularmente útil para:

• Probando rápidamente nuevos comandos
• Verificar la funcionalidad del complemento después de las actualizaciones
• Recreando escenas complejas para depuración
• Prueba de compatibilidad entre diferentes versiones de Cinema 4D

Solución de problemas y depuración

1. Compruebe los archivos de registro:
   tail -f ~/Library/Logs/Claude/mcp*.log
2. Verifique que Cinema 4D muestre conexiones en su consola después de abrir Claude Desktop.
3. Pruebe el script wrapper directamente:
   cinema4d-mcp-wrapper
4. Si hay errores al encontrar el módulo mcp, instálelo en todo el sistema:
   pip install mcp
5. Para una depuración avanzada, utilice el Inspector MCP :
   npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp

Estructura del archivo del proyecto

Comandos de herramientas

Escena general y ejecución

• get_scene_info : Obtener información resumida sobre la escena activa de Cinema 4D. ✅
• list_objects : Lista todos los objetos de la escena (con jerarquía). ✅
• group_objects : Agrupa los objetos seleccionados bajo un nuevo valor nulo. ✅
• execute_python : Ejecuta código Python personalizado dentro de Cinema 4D. ✅
• save_scene : Guarda el proyecto actual de Cinema 4D en el disco. ✅
• load_scene : Carga un archivo .c4d en la escena. ✅
• set_keyframe : Establece un fotograma clave en una propiedad de un objeto (posición, rotación, etc.). ✅

Creación y modificación de objetos

• add_primitive : Agrega un primitivo (cubo, esfera, cono, etc.) a la escena. ✅
• modify_object : Modificar la transformación o los atributos de un objeto existente. ✅
• create_abstract_shape : Crea una forma abstracta orgánica y no estándar. ✅

Cámaras y animación

• create_camera : Agrega una nueva cámara a la escena. ✅
• animate_camera : anima una cámara a lo largo de una ruta (lineal o basada en splines). ✅

Iluminación y materiales

• create_light : Agrega una luz (omni, spot, etc.) a la escena. ✅
• create_material : Crea un material estándar de Cinema 4D. ✅
• apply_material : Aplicar un material a un objeto de destino. ✅
• apply_shader : Genera y aplica un sombreador estilizado o procedimental. ✅

Soporte de Redshift

• validate_redshift_materials : Verifica la configuración y las conexiones de los materiales de Redshift. ✅ ⚠️ (Los materiales de Redshift no están completamente implementados)

MoGraph y campos

• create_mograph_cloner : Agrega un clonador MoGraph (lineal, radial, cuadrícula, etc.). ✅
• add_effector : Agrega un efector MoGraph (aleatorio, simple, etc.). ✅
• apply_mograph_fields : Agrega y vincula un campo MoGraph a objetos. ✅

Dinámica y física

• create_soft_body : Agrega una etiqueta Soft Body a un objeto. ✅
• apply_dynamics : Aplicar física de cuerpos rígidos o blandos. ✅

Renderizado y vista previa

• render_frame : Renderiza un fotograma y lo guarda en el disco (solo salida basada en archivos). ⚠️ (Funciona, pero falla en resoluciones grandes debido a MemoryError: Bitmap Init failed. Esto es una limitación de recursos).
• render_preview : Renderiza una vista previa rápida y devuelve una imagen base64 (para IA). ✅
• snapshot_scene : Captura una instantánea de la escena (objetos + imagen de vista previa). ✅

Plan y hoja de ruta de compatibilidad

Objetivos de compatibilidad

• A corto plazo : garantizar la compatibilidad con C4D 2023.1+ (Python 3.9 y 3.10)
• A medio plazo : agregar manejo condicional para las API de MoGraph y Field faltantes
• A largo plazo : considere un módulo de complemento heredado opcional para compatibilidad con R23–S26 si surge demanda

Correcciones recientes

• Conocimiento del contexto: Se implementó un seguimiento robusto de objetos mediante GUID. Los comandos que crean objetos devuelven el contexto (GUID, nombre_actual, etc.). Los comandos posteriores utilizan correctamente los GUID transmitidos por el servidor/argumento de prueba para encontrar objetos de forma fiable.
• Búsqueda de objetos: se modificó find_object_by_name para manejar correctamente los GUID (formato de cadena numérica), se corrigieron errores de recursión y se mejoró la confiabilidad cuando falla doc.SearchObject.
• Detección de GUID: los controladores de comandos (apply_material, create_mograph_cloner, add_effector, apply_mograph_fields, set_keyframe, group_objects) ahora detectan correctamente si los identificadores pasados en varios parámetros (object_name, target, target_name, elementos de lista) son GUID y buscan en consecuencia.
• create_mograph_cloner: Se corrigió un error de atributo por la falta de parámetros de MoGraph (como MG_LINEAR_PERSTEP) al usar alternativas getattr. Se corrigió un error lógico donde el objeto encontrado no se transfería correctamente para la clonación.
• Renderizado: Se corrigió un error de tipo en render_frame relacionado con doc.ExecutePasses. snapshot_scene ahora usa correctamente la lógica de renderizado base64. Los render_frames grandes aún enfrentan límites de memoria.
• Registro: Error de atributo corregido para c4d.NilGuid.