Unity Editor MCP Server

Editor de Unity de MCP (motor de juego)

MCP Unity es una implementación del Protocolo de Contexto de Modelo para el Editor de Unity, que permite a los asistentes de IA interactuar con tus proyectos de Unity. Este paquete proporciona un puente entre Unity y un servidor Node.js que implementa el protocolo MCP, lo que permite que agentes de IA como Claude, Windsurf y Cursor ejecuten operaciones dentro del Editor de Unity.

Características

Integración IDE: acceso a la caché de paquetes

MCP Unity proporciona integración automática con IDEs similares a VSCode (Visual Studio Code, Cursor, Windsurf) añadiendo la carpeta Unity Library/PackedCache a su espacio de trabajo. Esta función:

• Mejora la inteligencia del código para los paquetes de Unity
• Permite un mejor autocompletado y un mejor tipo de información para los paquetes de Unity
• Ayuda a los asistentes de codificación de IA a comprender las dependencias de su proyecto.

Herramientas del servidor MCP

• execute_menu_item : ejecuta elementos del menú de Unity (funciones etiquetadas con el atributo MenuItem)

  Ejemplo de mensaje: "Ejecute el elemento de menú 'GameObject/Crear vacío' para crear un nuevo GameObject vacío"

• select_gameobject : selecciona objetos de juego en la jerarquía de Unity por ruta o ID de instancia

  Ejemplo de mensaje: "Seleccionar el objeto de la cámara principal en mi escena"

• update_component : actualiza los campos del componente en un GameObject o lo agrega al GameObject si no contiene el componente

  Ejemplo de solicitud: "Agregue un componente Rigidbody al objeto Player y establezca su masa en 5"

• add_package : instala nuevos paquetes en el Administrador de paquetes de Unity

  Ejemplo de mensaje: "Agregar el paquete TextMeshPro a mi proyecto"

• run_tests : ejecuta pruebas utilizando Unity Test Runner

  Ejemplo de mensaje: "Ejecutar todas las pruebas de EditMode en mi proyecto"

• send_console_log : envía un registro de la consola a Unity

  Ejemplo de mensaje: "Enviar un registro de la consola al editor de Unity"

• add_asset_to_scene : agrega un activo de AssetDatabase a la escena de Unity

  Ejemplo de mensaje: "Agrega el prefab Player de mi proyecto a la escena actual"

Recursos del servidor MCP

• unity://menu-items : recupera una lista de todos los elementos de menú disponibles en el Editor de Unity para facilitar la herramienta execute_menu_item

  Ejemplo de mensaje: "Muéstrame todos los elementos de menú disponibles relacionados con la creación de GameObject"

• unity://hierarchy : recupera una lista de todos los objetos del juego en la jerarquía de Unity

  Ejemplo de mensaje: "Muéstrame la estructura jerárquica de la escena actual"

• unity://gameobject/{id} : recupera información detallada sobre un GameObject específico por ID de instancia o ruta de objeto en la jerarquía de la escena, incluidos todos los componentes del GameObject con sus propiedades y campos serializados

  Ejemplo de mensaje: "Obtén información detallada sobre el GameObject del jugador"

• unity://logs : recupera una lista de todos los registros de la consola de Unity

  Ejemplo de mensaje: "Muéstrame los mensajes de error recientes de la consola de Unity"

• unity://packages : recupera información sobre los paquetes instalados y disponibles del Administrador de paquetes de Unity

  Ejemplo de solicitud: "Enumerar todos los paquetes instalados actualmente en mi proyecto de Unity"

• unity://assets : recupera información sobre los activos en la base de datos de activos de Unity

  Ejemplo de solicitud: "Buscar todos los recursos de textura en mi proyecto"

• unity://tests/{testMode} : recupera información sobre las pruebas en Unity Test Runner

  Ejemplo de solicitud: "Enumerar todas las pruebas disponibles en mi proyecto de Unity"

Requisitos

• Unity 2022.3 o posterior: para instalar el servidor
• Node.js 18 o posterior: para iniciar el servidor
• npm 9 o posterior: para depurar el servidor

Instalación

La instalación de este servidor MCP Unity es un proceso de varios pasos:

Paso 1: Instale el paquete Unity MCP Server a través del Administrador de paquetes de Unity

1. Abra el Administrador de paquetes de Unity (Ventana > Administrador de paquetes)
2. Haga clic en el botón "+" en la esquina superior izquierda
3. Seleccione "Agregar paquete desde la URL de git..."
4. Ingresa: https://github.com/CoderGamester/mcp-unity.git
5. Haga clic en "Agregar"

Paso 2: Instalar Node.js

Para ejecutar el servidor MCP Unity, necesitará tener Node.js 18 o posterior instalado en su computadora:

1. Visita la página de descarga de Node.js
2. Descargue el instalador de Windows (.msi) para la versión LTS (recomendado)
3. Ejecute el instalador y siga el asistente de instalación.
4. Verifique la instalación abriendo PowerShell y ejecutando:
   node --version
5. Visita la página de descarga de Node.js
6. Descargue el instalador de macOS (.pkg) para la versión LTS (recomendado)
7. Ejecute el instalador y siga el asistente de instalación.
8. Alternativamente, si tienes Homebrew instalado, puedes ejecutar:
   brew install node@18
9. Verifique la instalación abriendo la Terminal y ejecutando:
   node --version

Paso 3: Configurar el cliente AI LLM

1. Abra el Editor de Unity
2. Vaya a Herramientas > MCP Unity > Ventana del servidor
3. Haga clic en el botón "Configurar" para su cliente AI LLM como se muestra en la imagen a continuación.

4. Confirme la instalación de la configuración con la ventana emergente que aparece

Abra el archivo de configuración MCP de su cliente AI (por ejemplo, claude_desktop_config.json en Claude Desktop) y copie el siguiente texto:

Reemplace ABSOLUTE/PATH/TO con la ruta absoluta a su instalación de MCP Unity o simplemente copie el texto desde la ventana del servidor MCP del editor de Unity (Herramientas > MCP Unity > Ventana del servidor).

Iniciar el servidor MCP de Unity Editor

1. Abra el Editor de Unity
2. Vaya a Herramientas > MCP Unity > Ventana del servidor
3. Haga clic en "Iniciar servidor" para iniciar el servidor WebSocket
4. Abra Claude Desktop o su IDE de codificación de IA (por ejemplo, Cursor IDE, Windsurf IDE, etc.) y comience a ejecutar las herramientas de Unity

Cuando el cliente de IA se conecta al servidor WebSocket, se mostrará automáticamente en el cuadro verde de la ventana.

Opcional: Establecer puerto WebSocket

De forma predeterminada, el servidor WebSocket se ejecuta en el puerto 8090. Puede cambiar este puerto de dos maneras:

1. Abra el Editor de Unity
2. Vaya a Herramientas > MCP Unity > Ventana del servidor
3. Cambie el valor de "Puerto WebSocket" al número de puerto deseado
4. Unity configurará la variable de entorno del sistema UNITY_PORT en el nuevo número de puerto
5. Reiniciar el servidor Node.js
6. Haga clic nuevamente en "Iniciar servidor" para volver a conectar el socket web del Editor de Unity al servidor MCP de Node.js
7. Establezca la variable de entorno UNITY_PORT en la terminal
   • Powershell GXP6
   • Símbolo del sistema/Terminal GXP7
8. Reiniciar el servidor Node.js
9. Haga clic nuevamente en "Iniciar servidor" para volver a conectar el socket web del Editor de Unity al servidor MCP de Node.js

Opcional: Establecer tiempo de espera

De forma predeterminada, el tiempo de espera entre el servidor MCP y el WebSocket es de 10 segundos. Puede modificarlo según el sistema operativo que utilice:

1. Abra el Editor de Unity
2. Vaya a Herramientas > MCP Unity > Ventana del servidor
3. Cambie el valor de "Tiempo de espera de solicitud (segundos)" a los segundos de tiempo de espera deseados.
4. Unity configurará la variable de entorno del sistema UNITY_REQUEST_TIMEOUT con el nuevo valor de tiempo de espera
5. Reiniciar el servidor Node.js
6. Haga clic nuevamente en "Iniciar servidor" para volver a conectar el socket web del Editor de Unity al servidor MCP de Node.js

Para sistemas operativos que no sean Windows, deberá configurar dos lugares:

Tiempo de espera del proceso en el editor

1. Abra el Editor de Unity
2. Vaya a Herramientas > MCP Unity > Ventana del servidor
3. Cambie el valor de "Tiempo de espera de solicitud (segundos)" a los segundos de tiempo de espera deseados.

Tiempo de espera de WebSocket

1. Establezca la variable de entorno UNITY_REQUEST_TIMEOUT en la terminal
   • Powershell GXP8
   • Símbolo del sistema/Terminal GXP9
2. Reiniciar el servidor Node.js
3. Haga clic nuevamente en "Iniciar servidor" para volver a conectar el socket web del Editor de Unity al servidor MCP de Node.js

[!CONSEJO]
El tiempo de espera entre su IDE de codificación de IA (por ejemplo, Claude Desktop, Cursor IDE, Windsurf IDE) y el servidor MCP depende del IDE.

Depuración del servidor

El servidor MCP Unity se compila con Node.js. Requiere compilar el código TypeScript a JavaScript en el directorio build . Para compilar el servidor, abra una terminal y:

1. Navegue hasta el directorio del servidor:
   cd ABSOLUTE/PATH/TO/mcp-unity/Server
2. Instalar dependencias:
   npm install
3. Construir el servidor:
   npm run build
4. Ejecutar el servidor:
   node build/index.js

Depure el servidor con @modelcontextprotocol/inspector :

• PowerShell

• Símbolo del sistema/Terminal

No olvide apagar el servidor con Ctrl + C antes de cerrar la terminal o depurarlo con el Inspector MCP .

1. Habilite el inicio de sesión en su terminal o en un archivo log.txt:
   • Powershell GXP16
   • Símbolo del sistema/Terminal GXP17

Solución de problemas

• Asegúrese de que el servidor WebSocket esté ejecutándose (verifique la ventana del servidor en Unity)
• Envíe un mensaje de registro de consola desde el cliente MCP para forzar una reconexión entre el cliente MCP y el servidor Unity
• Cambie el número de puerto en la ventana Servidor MCP del Editor de Unity. (Herramientas > MCP Unity > Ventana Servidor)
• Comprueba si hay mensajes de error en la consola de Unity
• Asegúrese de que Node.js esté correctamente instalado y accesible en su PATH
• Verifique que todas las dependencias estén instaladas en el directorio del servidor

La herramienta run_tests devuelve la siguiente respuesta:

Este error se produce porque la conexión del puente se pierde cuando el dominio se recarga al cambiar al modo de reproducción.
La solución alternativa es desactivar Recargar dominio en Editar > Configuración del proyecto > Editor > "Ingresar a la configuración del modo de reproducción" .

Soporte y comentarios

Si tiene alguna pregunta o necesita ayuda, abra un problema en este repositorio.

Alternativamente, puede comunicarse con nosotros en:

• Linkedin:
• Discord: gamester7178
• Correo electrónico: game.gamester@gmail.com

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios o abrir un problema con su solicitud.

Confirme sus cambios siguiendo el formato de confirmaciones convencionales .

Licencia

Este proyecto está bajo licencia MIT

Expresiones de gratitud

• Protocolo de contexto modelo
• Tecnologías de Unity
• Node.js
• WebSocket-Sharp