TouchDesigner MCP conecta agentes de IA con TouchDesigner mediante el Model Context Protocol y el WebServer DAT de TouchDesigner. El repositorio 8beeeaaat/touchdesigner-mcp lo describe como un servidor MCP que permite crear, modificar y eliminar nodos, leer la estructura del proyecto, controlar TouchDesigner mediante scripts Python y capturar la salida de un TOP como imagen. En la verificación de GitHub del 26 de agosto de 2026, el repositorio tenía licencia MIT, 505 estrellas y 51 forks, y la última release era v2.0.0, publicada el 30 de julio de 2026.
Para Educasium, este conector es pertinente para instalaciones visuales, escenografías interactivas, medios en tiempo real y prototipos creativos. Habla con una herramienta donde los grafos de nodos, parámetros y feedback visual importan más que una página estática. Aun así, hay que ser preciso: la instalación incluye un servidor MCP Node.js y un componente TouchDesigner, las versiones npm y API evolucionan en dos ejes distintos, y la herramienta expone execute_python_script.
Índice
- Qué hace TouchDesigner MCP
- Instalación y arquitectura
- Herramientas expuestas
- Versionado y compatibilidad
- Comparación con Blender, Houdini y Unity
- Seguridad y límites
- Posición Educasium
Qué hace TouchDesigner MCP
Resumen: TouchDesigner MCP sirve de puente entre un agente de IA y un proyecto TouchDesigner abierto, con acciones sobre nodos, parámetros, scripts e imágenes TOP. Está diseñado para un entorno visual en tiempo real, no para generar un sitio o un render final fuera de contexto.
Un puente hacia WebServer DAT
El README explica que TouchDesigner MCP actúa como puente entre modelos de IA y el WebServer DAT. Este punto es central: el agente no controla TouchDesigner por magia, envía solicitudes a una capa servidor expuesta dentro del proyecto. El proyecto TouchDesigner debe contener el componente mcp_webserver_base.tox, idealmente ubicado bajo project1/mcp_webserver_base según la guía de instalación.
El servidor MCP puede luego pedir operaciones sobre nodos, parámetros y estructura del proyecto. Para flujos creativos, esto abre usos simples: crear una base de red, modificar parámetros, leer errores, capturar un TOP e iterar. Para un flujo profesional, el mismo bucle debe seguir siendo observable, porque una instalación en tiempo real depende también del hardware, entradas, rendimiento y escenografía.
Por qué es distinto de un MCP 3D clásico
TouchDesigner no es solo un software de modelado. Se usa a menudo para sistemas visuales en tiempo real, interacción, video, sensores, performances e instalaciones. Un conector MCP tiene por eso un valor particular: ayudar a manipular una red viva, con parámetros cambiantes e imágenes de salida que deben verificarse.
El comando get_top_image es importante en esa lógica. Captura la salida actual de un TOP como imagen. Eso da al modelo feedback visual sobre el resultado producido, aunque la decisión artística y técnica sigue siendo humana. Para Educasium, este bucle creación, captura, corrección es más formativo que una simple lista de comandos.
Instalación y arquitectura
Resumen: la instalación requiere un componente TouchDesigner en el proyecto y un servidor MCP lanzado por bundle Claude Desktop, npm o Docker. Si falta uno de los dos lados, se corta la conexión.
Instalación del lado TouchDesigner
La guía de instalación pide primero descargar touchdesigner-mcp-td.zip desde la última release, extraer el ZIP e importar mcp_webserver_base.tox en el proyecto TouchDesigner. Recomienda la ruta project1/mcp_webserver_base. También insiste en un punto práctico: no cambiar la estructura de carpetas, porque el componente referencia los módulos con rutas relativas.
La última release verificada contenía dos assets: touchdesigner-mcp-td.zip y touchdesigner-mcp.mcpb. El primero corresponde al lado TouchDesigner. El segundo corresponde al bundle MCP para Claude Desktop. Para una formación, conviene preparar ambos archivos y probar el Textport antes de la sesión.
Servidor MCP Node.js
El paquete npm verificado se llama touchdesigner-mcp-server, versión 2.0.0, type module, con un binario touchdesigner-mcp-server que apunta a dist/cli.js. La guía indica que las instalaciones npm para Claude Code, Codex y otros clientes usan npx -y touchdesigner-mcp-server@latest --stdio. Precisa que Node.js 20.x o superior es requerido para instalaciones npm.
La arquitectura oficial describe dos procesos: un servidor MCP Node.js y un WebServer Python dentro de TouchDesigner. El servidor Node.js puede funcionar en stdio para una conexión local uno a uno, o en modo Streamable HTTP para usos HTTP/SSE. Luego el servidor se comunica con TouchDesigner mediante la API HTTP expuesta por el WebServer DAT, por defecto en http://127.0.0.1:9981.
Herramientas expuestas
Resumen: las herramientas cubren creación de nodos, eliminación, parámetros, introspección Python, errores, ejecución de scripts y captura TOP. Esta cobertura encaja bien con demostraciones en tiempo real y talleres sobre grafos TouchDesigner.
Nodos y parámetros
La tabla README lista create_td_node para crear un nodo, delete_td_node para eliminar, get_td_nodes para listar nodos bajo un padre con filtrado, get_td_node_parameters para leer parámetros y update_td_node_parameters para modificarlos. También lista get_td_node_errors para verificar errores de un nodo y de sus hijos.
Estos comandos permiten una progresión pedagógica clara. El alumno puede pedir la creación de una pequeña red, leer los parámetros disponibles, modificar un ajuste y luego consultar los errores. En TouchDesigner, este bucle es importante, porque un error de ruta, tipo de nodo o parámetro puede dejar parte de la red inactiva sin producir una señal evidente para principiantes.
Python, clases e imagen TOP
El README lista execute_python_script para ejecutar un script Python arbitrario en TouchDesigner, exec_node_method para llamar un método Python sobre un nodo, get_td_classes para obtener la lista de clases Python TouchDesigner, get_td_class_details para obtener el detalle de una clase o módulo, y get_td_module_help para consultar la ayuda Python. Estas herramientas convierten el conector en asistente de scripting, no solo en editor de parámetros.
get_top_image captura la salida actual de un nodo TOP como imagen. Para instalaciones visuales, es la herramienta que vuelve la iteración más concreta: el asistente puede ver una salida, comentar el resultado y proponer una corrección. Esta capacidad no sustituye una verificación en pantalla real, proyector, LED wall o dispositivo interactivo, pero da un primer bucle de control.
Versionado y compatibilidad
Resumen: TouchDesigner MCP separa la versión del paquete npm y la versión API del componente TouchDesigner. Es la trampa operativa más importante para actualizaciones.
Dos ejes de versión
El README explica que el servidor MCP y el componente TouchDesigner se versionan en dos ejes independientes: la versión del paquete npm y la versión API, que representa el contrato entre el servidor MCP y el componente .tox. Cada release declara expectedApiVersion y minApiVersion. El mínimo indicado en el README verificado es 1.3.0.
Esta regla evita un error frecuente: creer que actualizar el paquete npm basta. El README dice explícitamente que la versión npm no bloquea nunca la compatibilidad por sí sola. Lo que importa es la compatibilidad entre la API esperada por el servidor y la API expuesta por el componente TouchDesigner.
Comportamientos ante diferencias
La tabla de troubleshooting indica que un componente con la versión API esperada funciona sin avisos. Una versión más antigua pero por encima del mínimo dispara una advertencia de actualización recomendada y continúa. Una versión más nueva dentro del mismo major también dispara una advertencia. En cambio, un major por encima del esperado o una versión por debajo del mínimo detiene la ejecución.
La guía también da la corrección: descargar el último touchdesigner-mcp-td.zip, reemplazar el directorio existente, eliminar el viejo componente mcp_webserver_base en el proyecto, importar el nuevo .tox y reiniciar TouchDesigner y el agente de IA. Para Educasium, es una sección que conviene mantener en el soporte de curso, porque evita muchos diagnósticos falsos.
Comparación con Blender, Houdini y Unity
Resumen: TouchDesigner MCP es la mejor opción de esta lista cuando el tema es una instalación visual en tiempo real o una red interactiva. No cumple el mismo rol que un MCP de modelado o de motor de juego.
| Opción | Uso natural | Fuerza principal | Límite a vigilar |
|---|---|---|---|
| TouchDesigner MCP | Instalaciones visuales, tiempo real, TOP y redes interactivas | Parámetros, errores, scripts y captura TOP | Versión API del componente .tox a mantener |
| Blender MCP | Iniciación 3D, assets y escenas accesibles | Software gratuito y comunidad amplia | Menos orientado a performance live y sensores |
| Houdini MCP | Grafos procedurales, wrangles, VFX | Redes node-based y geometría procedural | Más técnico, centrado en Houdini |
| Unity MCP | Escenas interactivas, juegos, visitas en tiempo real | Motor de ejecución y assets de juego | Workflow más pesado que un patch TouchDesigner |
Elegir según la salida esperada
Si el objetivo es una imagen, una escena 3D o una asset library, TouchDesigner no es necesariamente el punto de entrada más simple. Si el objetivo es una experiencia en tiempo real que reacciona a parámetros, un flujo de video o una interacción, TouchDesigner MCP se vuelve mucho más natural.
Esta distinción ayuda a Educasium a segmentar cursos. Un módulo Blender enseña la escena 3D. Un módulo Houdini enseña procedural avanzado. Un módulo TouchDesigner enseña iteración live: red, parámetros, salida TOP, errores, rendimiento y recuperación del control humano.
Seguridad y límites
Resumen: la capacidad execute_python_script debe tratarse como una verdadera superficie de ejecución dentro de TouchDesigner. Los beneficios de automatización no justifican dejar al agente actuar sin control en un proyecto cliente o instalación activa.
Scripts arbitrarios
El README nombra execute_python_script como ejecución de un script Python arbitrario dentro de TouchDesigner. Es útil para inspeccionar, automatizar o corregir lo que las herramientas estructuradas no cubren. También es el punto que impone reglas: trabajar sobre copia, revisar el script, limitar accesos a archivos y no probar directamente sobre un show file crítico.
exec_node_method exige la misma prudencia. Llamar un método Python sobre un nodo puede ser legítimo, pero depende del nodo, del contexto y de los efectos secundarios. En formación, es mejor empezar por herramientas estructuradas de lectura, parámetros y errores antes de pasar a scripts.
Conexión y transporte
El modo stdio es local y uno a uno, mientras que el modo Streamable HTTP puede ser accesible por red según la configuración. La guía de instalación describe también Docker y variables como MCP_HTTP_PORT o TD_HOST para casos HTTP. Puede ser útil en desarrollo, pero no es la opción más simple para una iniciación.
Los errores de conexión están documentados con causas concretas: TouchDesigner no lanzado, WebServer DAT ausente o detenido, puerto por defecto 9981 incorrecto, timeout, nombre de host inválido. El cliente también cachea los fallos de conexión durante 60 segundos para evitar saturar TouchDesigner. Es un detalle útil para diagnosticar una demo que acaba de repararse pero sigue respondiendo con un error antiguo.
Posición Educasium
Resumen: Educasium puede presentar TouchDesigner MCP como un excelente caso de estudio para IA aplicada a entornos visuales en tiempo real, con fuerte énfasis en versionado, seguridad y verificación visual. El posicionamiento sigue siendo experimental mientras no exista validación de producción documentada.
Formación propuesta
Un taller razonable empieza por la instalación: importar mcp_webserver_base.tox, mantener la estructura de carpetas, verificar el Textport, instalar el bundle Claude Desktop o configurar npx para Codex y lanzar una primera llamada get_td_info. Solo después pasa a una mini red: crear un nodo, leer sus parámetros, modificar un valor, verificar errores y capturar un TOP.
Esta progresión enseña un método sólido. El alumno entiende que el asistente necesita un componente activo, un puerto correcto, una API compatible y validación visual. También aprende a distinguir un problema de prompt de un problema de conexión o versión.
Siguiente paso lógico
El siguiente paso sería una grilla Educasium para probar MCP de tiempo real: instalación, puerto, transporte, versión API, herramientas de lectura, herramientas de escritura, scripts arbitrarios, captura de imagen, rendimiento y rollback. TouchDesigner MCP es un buen candidato para esa grilla porque ya documenta muchos de esos puntos.