Unity Editor MCP

Permite que los asistentes de IA interactúen directamente con el Unity Editor para el desarrollo de juegos asistido por IA y la automatización.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Unity Editor MCP

CI codecov License: MIT npm version

⚠️ Este proyecto está en beta y en desarrollo activo. Las funciones y API pueden cambiar. Úsalo bajo tu propio criterio.

Unity Editor MCP (Model Context Protocol) permite que asistentes de IA como Claude y Cursor interactúen directamente con el Editor de Unity, facilitando el desarrollo de juegos asistido por IA y la automatización.

🚀 Funciones principales

  • 🎮 Gestión de GameObjects: Crea primitivas, modifica transformaciones, gestiona la jerarquía y elimina objetos
  • 🔧 Sistema de componentes: Añade, elimina, modifica y lista componentes en GameObjects con control total de propiedades
  • 🎭 Flujo de trabajo con Prefabs: Edición completa en modo prefab: abrir, modificar, guardar y salir con gestión de overrides
  • 🔍 Búsqueda inteligente: Encuentra GameObjects por nombre, etiqueta, capa o tipo de componente con coincidencia exacta/parcial
  • 📊 Análisis de escena: Analiza la composición de la escena, estadísticas de componentes y conexiones de prefabs
  • 🎯 Inspección de componentes: Obtén valores de componentes, encuentra objetos por componente, rastrea referencias entre objetos
  • 🎬 Control de escena: Crea, carga, guarda escenas, gestiona ajustes de compilación y trabaja con múltiples escenas
  • 🏃 Pruebas en modo Play: Inicia, pausa y detén el modo play, verifica el estado del editor y el estado de compilación
  • 🖼️ Captura de pantallas: Toma capturas de la vista de juego o de escena con capacidades de análisis
  • 🎨 Gestión de assets: Crea y modifica prefabs, materiales y scripts con control integral de propiedades
  • 🖱️ Automatización de UI: Interactúa con elementos de UI de Unity programáticamente para pruebas y automatización
  • 📝 Integración de consola: Lee registros de la consola de Unity filtrados por tipo con funciones de depuración mejoradas
  • 🔄 Operaciones del editor: Actualiza assets, ejecuta elementos de menú y activa la recompilación

📌 Novedades

Paquete Unity 0.16.0

Menor, no parche: esta versión cambia el contrato de una herramienta y añade una dependencia de paquete, que es lo que el esquema 0.x aquí incrementa en la versión menor (0.15.0 añadió las herramientas del Test Runner de la misma manera). El paquete del servidor Node tiene su propia versión independiente y no cambia.

Cambios importantes

  • run_tests ahora requiere testMode. Pasa "EditMode", "PlayMode" o "EditAndPlayMode" explícitamente; no hay valor predeterminado, porque PlayMode y EditAndPlayMode entran en modo play y activan una recarga de dominio, y elegir eso silenciosamente para un llamador que quería EditMode era un riesgo. Un servidor MCP más antiguo que este paquete fallará en cada llamada a run_tests, con testMode is required, porque no envía el campo. Actualiza el servidor Node (npx unity-editor-mcp@latest) junto con el paquete de Unity.
  • Nueva dependencia de paquete: com.unity.ugui 2.0.0. Las herramientas de interacción con UI hacen referencia a tipos de uGUI, por lo que la dependencia ahora se declara en lugar de asumirse. Unity la resuelve automáticamente; un proyecto que había eliminado deliberadamente uGUI la verá regresar.

Las ejecuciones de pruebas son honestas sobre su propio estado

  • get_test_results informa runStatus, runGuid, secondsSinceLastProgress y possiblyStale, y nunca muta el estado de ejecución: la consulta ya no puede abandonar una ejecución que simplemente era lenta.
  • cancel_tests informa lo que realmente sucedió. Si la API del Test Runner no acepta la cancelación, la ejecución se deja intacta y se te informa, en lugar de reportar una cancelación que nunca ocurrió.
  • run_tests acepta force: true, que ahora realmente cancela primero la ejecución en curso y se niega a iniciar una segunda cuando la cancelación no está disponible y la ejecución anterior no se puede confirmar como terminada. Ya no es posible que dos ejecuciones concurrentes informen en un mismo conjunto de resultados.
  • Los resultados sobreviven a la recarga de dominio que causa una ejecución en modo Play, y los resultados posteriores a la recarga ya no se descartan por una consulta a mitad de ejecución.

El puente sigue respondiendo mientras el hilo principal del editor está ocupado

  • ping y get_editor_state se responden en el hilo del socket desde el estado en caché, y llevan mainThreadResponsive, mainThreadLastTickSecondsAgo, mainThreadInFlightCommand y mainThreadInFlightSeconds, para que un cliente pueda ver en qué está atascado el editor y durante cuánto tiempo.
  • Los comandos que no se pueden atender de esa manera fallan con un error MAIN_THREAD_STALLED que nombra el comando en curso en lugar de colgarse hasta un tiempo de espera opaco. Un manejador que mantiene el hilo principal más allá del límite de 600 segundos se informa una vez por manejador, no una vez por segundo.

Registro de instancias

  • Las entradas del registro cuyo proceso de Unity ya no existe se eliminan automáticamente, por lo que los editores bloqueados o cerrados a la fuerza dejan de ralentizar el descubrimiento. Establece UNITY_MCP_DISABLE_REGISTRY_PRUNE=true para optar por no participar.
  • Las entradas se escriben atómicamente, y el puerto de escucha que Unity realmente vinculó se vuelve a publicar inmediatamente después de una recarga de dominio.

Solución de problemas

Un diálogo modal abierto en Unity y un Editor en segundo plano limitado por App Nap de macOS detienen el bucle del editor y parecen exactamente un cuelgue. Consulta Los comandos se cuelgan o devuelven MAIN_THREAD_STALLED para saber cómo diferenciarlos y qué hacer.

🚀 Inicio rápido

Requisitos previos

  • ✅ Unity 2020.3 LTS o más reciente
  • ✅ Node.js 18.0.0 o más reciente
  • ✅ Claude Desktop o Cursor

Instalación

📦 Paso 1: Instala el paquete de Unity

En Unity:

  1. Abre Window → Package Manager
  2. Haz clic en "+" → "Add package from git URL..."
  3. Pega: https://github.com/ozankasikci/unity-editor-mcp.git?path=unity-editor-mcp
  4. Haz clic en Add

✨ Unity iniciará automáticamente el puente MCP. Usa el puerto 6400 cuando esté disponible y recurre a un puerto local libre cuando haya múltiples instancias de Unity abiertas.

⚙️ Paso 2: Configura tu cliente MCP

Para Claude Desktop:

Añade a tu archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "unity-editor-mcp": {
      "command": "npx",
      "args": ["unity-editor-mcp@latest"]
    }
  }
}

Para Cursor:

Añade la misma configuración en los ajustes de MCP de Cursor

✅ Paso 3: Verifica la conexión

  1. Reinicia tu cliente MCP (Claude Desktop o Cursor)
  2. Revisa la consola de Unity para ver: [Unity Editor MCP] Client connected
  3. ¡Estás listo para empezar! 🎮

Múltiples instancias de Unity

Unity Editor MCP ahora descubre automáticamente los proyectos de Unity en ejecución. Cada instancia del Editor de Unity escribe una entrada de registro de runtime interno en ~/.unity-editor-mcp/instances, incluyendo su ruta de proyecto, ID de proceso, puerto, versión de Unity, versión del paquete, ID de espacio de trabajo, metadatos de worktree de Git y marca de tiempo de heartbeat. No edites este archivo.

Cuando el servidor Node MCP se inicia, selecciona la instancia de Unity en este orden:

  1. UNITY_PORT o --port, si se proporcionan explícitamente
  2. UNITY_MCP_INSTANCE_ID o --instance
  3. UNITY_PROJECT_PATH, UNITY_MCP_PROJECT_PATH o --project
  4. UNITY_MCP_WORKSPACE_ID o --workspace-id
  5. el proyecto de Unity inferido del directorio de trabajo actual
  6. el ID de espacio de trabajo estable inferido del directorio de trabajo actual
  7. la única instancia activa de Unity MCP, si existe exactamente una

Para worktrees de Git, el ID de espacio de trabajo se almacena en los metadatos privados del worktree de Git mediante git rev-parse --git-path unity-editor-mcp/workspace-id. Para proyectos que no son de Git, se almacena en Library/UnityEditorMCP/workspace-id. No se escribe en archivos de proyecto de Unity rastreados.

Si el servidor infiere un proyecto/espacio de trabajo local de Unity desde el directorio de trabajo actual, requiere una coincidencia exacta de proyecto o espacio de trabajo y no usa el recurso de instancia única activa. Si hay worktrees relacionados del mismo repositorio de Git abiertos pero ninguno coincide con el worktree actual, falla de forma segura con una lista de candidatos WORKTREE_MISMATCH en lugar de conectarse silenciosamente. Para restaurar el recurso de conveniencia anterior explícitamente, establece UNITY_MCP_ALLOW_SINGLE_INSTANCE_FALLBACK=true o pasa --allow-single-instance-fallback.

Para inspeccionar el descubrimiento sin iniciar una sesión MCP:

unity-editor-mcp doctor
unity-editor-mcp doctor --project /path/to/UnityProject
unity-editor-mcp doctor --workspace-id <workspace-id>
unity-editor-mcp doctor --instance <instance-id>
unity-editor-mcp doctor --allow-single-instance-fallback
unity-editor-mcp doctor --json

Herramientas disponibles

Unity Editor MCP proporciona 63 herramientas integrales en 11 categorías para la automatización completa del Editor de Unity:

Herramientas de sistema y núcleo (3 herramientas)

  • ping - Prueba la conexión con el Editor de Unity y verifica el estado del servidor
  • read_logs - Lee los registros de la consola de Unity con filtrado por tipo (Log, Warning, Error, etc.)
  • refresh_assets - Actualiza los assets de Unity y opcionalmente espera a que la compilación se estabilice

Gestión de GameObjects (5 herramientas)

  • create_gameobject - Crea GameObjects con primitivas, transformaciones, etiquetas y capas
  • find_gameobject - Encuentra GameObjects por nombre, etiqueta, capa con coincidencia de patrones
  • modify_gameobject - Modifica propiedades de GameObjects (transformación, nombre, estado activo, padre, etc.)
  • delete_gameobject - Elimina uno o múltiples GameObjects con manejo opcional de hijos
  • get_hierarchy - Obtén la jerarquía completa de la escena con componentes y control de profundidad

Sistema de componentes (5 herramientas)

  • add_component - Añade componentes de Unity a GameObjects con valores de propiedad iniciales
  • remove_component - Elimina componentes de GameObjects con comprobaciones de seguridad (evita la eliminación de Transform)
  • modify_component - Modifica propiedades de componentes con soporte para propiedades anidadas usando notación de puntos
  • list_components - Lista todos los componentes de un GameObject con información de tipo y estado de eliminación
  • get_component_types - Descubre tipos de componentes disponibles con filtrado por categoría y capacidad de adición

Gestión de escenas (5 herramientas)

  • create_scene - Crea nuevas escenas con integración de ajustes de compilación y carga automática
  • load_scene - Carga escenas existentes en modo Single o Additive
  • save_scene - Guarda la escena actual con funcionalidad de Guardar como
  • list_scenes - Lista todas las escenas del proyecto con filtrado e información de ajustes de compilación
  • get_scene_info - Obtén información detallada de la escena incluyendo recuentos de GameObjects

Análisis de escena (5 herramientas)

  • get_gameobject_details - Inspección profunda de GameObjects con detalles de componentes y jerarquía
  • analyze_scene_contents - Estadísticas integrales de escena, composición y métricas de rendimiento
  • get_component_values - Obtén todas las propiedades y valores de componentes específicos con metadatos
  • find_by_component - Encuentra GameObjects por tipo de componente con filtrado de alcance (escena/prefabs/todos)
  • get_object_references - Analiza referencias entre objetos incluyendo jerarquía y conexiones de assets

Gestión de assets (11 herramientas)

  • create_prefab - Crea prefabs a partir de GameObjects o plantillas vacías con opciones de sobrescritura
  • modify_prefab - Modifica prefabs existentes con cambios de propiedades y actualizaciones de instancias
  • instantiate_prefab - Instancia prefabs en escenas con opciones de transformación y parentesco
  • open_prefab - Abre prefabs en el modo prefab de Unity para edición detallada con enfoque y aislamiento
  • exit_prefab_mode - Sale del modo prefab con opciones de guardar/descartar cambios
  • save_prefab - Guarda cambios de prefab en modo prefab o aplica overrides de instancia a assets de prefab
  • create_material - Crea nuevos materiales con asignación de shader y configuración de propiedades
  • modify_material - Modifica materiales existentes con cambios de shader y actualizaciones de propiedades
  • manage_asset_import_settings - Gestiona los ajustes de importación de assets de Unity (obtener, modificar, aplicar presets, reimportar)
  • manage_asset_database - Gestiona operaciones de la Asset Database de Unity (buscar, información, crear carpetas, mover, copiar, eliminar, actualizar)
  • analyze_asset_dependencies - Analiza dependencias de assets de Unity (obtener dependencias, dependientes, dependencias circulares, assets no utilizados, impacto de tamaño)

Gestión de scripts (6 herramientas)

  • create_script - Crea nuevos scripts de C# con plantillas y gestión de espacios de nombres
  • read_script - Lee el contenido de archivos de script con información de resaltado de sintaxis
  • update_script - Modifica scripts existentes con reemplazo de contenido y validación
  • delete_script - Elimina archivos de script con comprobación de dependencias y confirmación
  • list_scripts - Lista todos los scripts del proyecto con filtrado y metadatos
  • validate_script - Valida la sintaxis de scripts y verifica errores de compilación

Controles de modo Play (4 herramientas)

  • play_game - Inicia el modo play de Unity para pruebas e interacción
  • pause_game - Pausa o reanuda el modo play de Unity
  • stop_game - Detiene el modo play de Unity y regresa al modo edición
  • get_editor_state - Obtén el estado actual del editor de Unity (modo play, pausa, estado de compilación)

Automatización de UI (5 herramientas)

  • find_ui_elements - Localizar elementos de UI en la jerarquía de escena con filtrado
  • click_ui_element - Simular clics en elementos de UI (botones, interruptores, etc.)
  • get_ui_element_state - Obtener estado detallado de elementos de UI y capacidades de interacción
  • set_ui_element_value - Establecer valores para elementos de entrada de UI (deslizadores, campos de entrada, etc.)
  • simulate_ui_input - Ejecutar secuencias complejas de interacción de UI

Operaciones del Editor (5 herramientas)

  • execute_menu_item - Ejecutar elementos de menú de Unity programáticamente con comprobaciones de seguridad
  • clear_console - Limpiar registros de consola de Unity con filtrado opcional
  • enhanced_read_logs - Lectura avanzada de registros con capacidades de búsqueda, filtrado y exportación
  • capture_screenshot - Tomar capturas de pantalla de la Vista de Juego o Vista de Escena con resolución y codificación personalizadas
  • analyze_screenshot - Analizar contenido de capturas de pantalla con capacidades básicas de análisis de imágenes

Control y Automatización del Editor (9 herramientas)

  • manage_tags - Gestionar etiquetas de proyectos de Unity (agregar, eliminar, listar)
  • manage_layers - Gestionar capas de proyectos de Unity (agregar, eliminar, listar, convertir índice/nombre)
  • manage_selection - Gestionar selección del Editor de Unity (obtener, establecer, limpiar, obtener detalles)
  • manage_windows - Gestionar ventanas del Editor de Unity (listar, enfocar, obtener estado)
  • manage_tools - Gestionar herramientas y complementos del Editor de Unity (listar, activar, desactivar, actualizar)
  • start_compilation_monitoring - Iniciar monitoreo de compilación de Unity con detección de errores en tiempo real
  • stop_compilation_monitoring - Detener monitoreo de compilación y obtener estado final
  • get_compilation_state - Obtener estado actual de compilación de Unity y errores
  • wait_for_compilation - Esperar a que la compilación/recarga de dominio de Unity se estabilice y devolver mensajes finales

Solución de Problemas

Problemas con el Listener TCP de Unity

Si ves "El puerto 6400 ya está en uso":

  1. Esto es esperado cuando otra instancia de Unity ya posee el puerto predeterminado
  2. El paquete recurrirá automáticamente a un puerto local disponible
  3. El puerto de respaldo se mantiene durante el resto de la sesión y no se mueve silenciosamente de vuelta a 6400 más tarde; el servidor Node sigue al editor a través del registro de instancias (ID de proceso y ruta del proyecto), por lo que el número de puerto no necesita ser estable
  4. Ejecuta unity-editor-mcp doctor para ver qué proyecto y puerto se seleccionarán

Un puerto fijo solo importa si optas por no usar el descubrimiento con UNITY_PORT / --port. En ese caso, asegúrate de que el puerto que fijas sea el que Unity realmente vinculó, que es lo que reporta unity-editor-mcp doctor.

Conexión Fallida

  1. Asegúrate de que el Editor de Unity esté ejecutándose con el paquete instalado
  2. Revisa la consola de Unity para ver mensajes de error
  3. Verifica que el servidor Node.js esté ejecutándose
  4. Comprueba que la ruta de configuración de tu cliente MCP sea absoluta

Comandos que se Cuelgan o Devuelven MAIN_THREAD_STALLED

Casi todas las herramientas deben ejecutarse en el hilo principal de Unity, por lo que solo pueden responder mientras el bucle del editor esté bombeando. Cuando el bucle se detiene, los comandos se ponen en cola en lugar de completarse.

Lo que hace el puente al respecto:

  • ping y get_editor_state se responden en el hilo del socket desde el estado en caché, por lo que siguen funcionando mientras el hilo principal está atascado. Ambos reportan mainThreadResponsive, mainThreadLastTickSecondsAgo, mainThreadInFlightCommand y mainThreadInFlightSeconds — úsalos para distinguir "Unity está congelado" de "el puente está ocupado ejecutando el comando que acabas de enviar" y de "el puente está caído".
  • Los comandos en cola fallan con MAIN_THREAD_STALLED en lugar de colgarse hasta el tiempo de espera del cliente. El error nombra el comando y cuánto tiempo ha estado silencioso el bucle.
  • Un comando de larga duración nuestro no es un estancamiento. Mientras el editor está dentro de uno de nuestros manejadores (refresh_assets, una importación grande, entrar en modo de reproducción), los comandos detrás de él siguen esperando, y el error, si se alcanza eventualmente el límite de 600s, nombra el comando que está reteniendo el hilo principal. Ese informe ocurre una vez por manejador atascado, no una vez por segundo, por lo que los comandos en cola detrás de él después siguen esperando en lugar de fallar en cada tick del vigilante.

Causas comunes, en orden de probabilidad:

  1. Un diálogo modal está abierto en Unity. Los diálogos modales bloquean completamente el bucle del editor; nada que el puente haga puede despertarlo. Trae Unity al frente y descarta el diálogo.
  2. La ventana del Editor está oculta o completamente cubierta en macOS, por lo que App Nap la limita y el bucle funciona a paso de tortuga. Descubrir la ventana lo soluciona. Si necesitas que Unity siga ejecutándose mientras está oculto, puedes optar por deshabilitar App Nap tú mismo — esto es una configuración del sistema aplicada por el usuario, no algo que el paquete haga: 
    defaults write com.unity3d.UnityEditor5.x NSAppSleepDisabled -bool YES
    Reinicia Unity después. (Verificado contra /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Info.plist; instalaciones de Unity más antiguas pueden usar un identificador de paquete diferente, así que verifica el tuyo antes de ejecutar esto.)
  3. Una importación larga, compilación de scripts o transición de modo de reproducción está en progreso. Espera a que termine; el comando se completa una vez que el bucle se reanuda.

Ten en cuenta que pedirle a Unity que drene su cola desde el hilo del socket solo reduce la latencia mientras el bucle está ya ejecutándose — no puede reiniciar un bucle que se ha detenido.

El Servidor Node.js No Se Inicia

  1. Asegúrate de tener Node.js 18+ instalado: node --version
  2. Ejecuta npm install en el directorio mcp-server
  3. Revisa cualquier mensaje de error en la consola

Contribuciones

Consulta CONTRIBUTING.md para las pautas de desarrollo.

Licencia

Licencia MIT - consulta LICENSE para más detalles.