Unity MCP Server

Servidor MCP para el Unity Editor. Permite que agentes de IA como Claude Code inspeccionen, manipulen, prueben y capturan capturas de pantalla de tu proyecto.

Características destacadas

• 73 herramientas: escenas, GameObjects, componentes, prefabs, transformaciones, pruebas, reflexión + descompilación, evaluación de C#, captura de UI

• Clientes sin configuración: un clic (o un comando) por máquina, y luego cada proyecto y editor se conecta automáticamente. Sin puertos, sin tokens, sin configuración por proyecto

• Seguro con múltiples editores: cada proyecto abierto ejecuta su propio servidor, las sesiones se enrutan al correcto automáticamente

• Recursos MCP: registros de consola, jerarquía de escenas, resultados de pruebas, archivos de proyecto

• Unity 2022.3+ (se recomienda Unity 6), Node.js 18+

Related MCP server: Unity MCP Server

Instalación

Package Manager > + > Add package from git URL:

https://github.com/Singtaa/UnityMCP.git

O clona / añade como submódulo en Packages/com.singtaa.unity-mcp.

Configuración (una vez por máquina)

1. Abre el proyecto en Unity. El servidor se inicia automáticamente, el lanzador se despliega en ~/.unity-mcp/stdio.js

2. Window > Unity MCP Server > Set up Claude Code

Listo. Equivalente en terminal:

# macOS / Linux
claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

# Windows
claude mcp add --scope user --transport stdio unity -- node "%USERPROFILE%\.unity-mcp\stdio.js"

Cada sesión de Claude Code dentro de cualquier proyecto de Unity llega ahora al editor de ese proyecto. Con varios editores en paralelo: cada sesión encuentra el suyo. Si el editor está cerrado o en medio de una recarga: las herramientas devuelven un error claro y se recuperan solas. Abrir el editor a mitad de sesión también funciona: una sesión iniciada con el editor cerrado registra la lista de herramientas de inmediato (servida desde una caché por proyecto) y se re-sincroniza en vivo en cuanto el editor aparece, sin necesidad de reiniciar el cliente.

En segundo plano: el editor escribe una baliza por sesión (Temp/UnityMcp_Endpoint.json, eliminada al salir, nunca obsoleta). El lanzador resuelve el proyecto de la sesión (CLAUDE_PROJECT_DIR, si no, subida por el cwd, UNITY_MCP_PROJECT tiene prioridad sobre ambos) y hace de proxy MCP hacia el endpoint en vivo de ese proyecto, releyendo la baliza en cada solicitud. Declara tools.listChanged y vigila la baliza: cuando aparece un editor (o uno distinto toma el proyecto), emite notificaciones list_changed para que los clientes vuelvan a obtener las listas de herramientas y recursos a mitad de sesión. El despliegue del lanzador en ~/.unity-mcp/stdio.js solo se actualiza según LAUNCHER_VERSION, por lo que editores con versiones distintas del paquete nunca compiten por el archivo.

Otros clientes MCP: el mismo lanzador, o HTTP simple (endpoint + token mostrados en la ventana).

Herramientas

Destacables:

• unity_eval: compila y ejecuta un fragmento de C# en el editor, sin recarga de dominio. La forma de expresión devuelve su valor, la forma de sentencia usa return. Usings comunes importados, líneas using iniciales elevadas. Roslyn incluido (tope C# 9). La primera llamada tarda unos segundos en arrancar, luego decenas de ms por compilación

• unity_capture_panel: renderiza un PanelSettings de UI Toolkit a PNG fuera de pantalla, sin chrome de escena, funciona en modo edición y play. Detecta automáticamente el UIDocument activo

• unity_assets_find: sintaxis de consulta de la Project window (t:Material, t:Prefab ui, l:MyLabel), ámbito de carpeta opcional, resultados limitados con recuento total

• unity_reflection_decompile: código fuente C# completo de cualquier tipo o método cargado

• Particularidades: espera ~1s tras una recarga de dominio antes de las herramientas de prueba; unity_capture_game_view solo funciona en play mode en Unity 6.3+

Recursos

unity://console/logs · unity://hierarchy · unity://hierarchy/{scene} · unity://tests/results · unity://project/files

Configuración

ProjectSettings/McpSettings.json (pensado para commitearse): puerto HTTP 5173, puerto IPC 52100, auto-inicio, token de autenticación.

¿Puertos ocupados por el servidor de otro proyecto? Se asigna automáticamente un par libre y se guarda por máquina en UserSettings/McpPortOverride.json (gitignored), así los cambios de puerto nunca llegan al equipo. La identidad del proyecto se valida en cada conexión del bridge: un editor nunca puede adoptar el servidor de otro proyecto, incluso con puertos mal configurados.

Inicio manual del servidor: node src/server.js con MCP_PROJECT_ROOT establecido en la ruta del proyecto.

Compatible con Unity CLI

Complementario, no competidor:

• Unity CLI gestiona el ciclo de vida del editor: instalaciones, unity open, builds, CI

• UnityMCP gestiona la sesión en vivo del editor: captura de UI, descompilación, eval, bucles de prueba, enrutamiento sin configuración

• Bucle típico del agente: unity open <project> mediante CLI, el editor arranca, el servidor y la baliza se levantan, el lanzador se conecta. Sin configuración en ninguno de los dos lados

• Los editores lanzados por CLI se ejecutan sin foco / en segundo plano. UnityMCP está construido y probado precisamente para eso (arranque seguro en segundo plano, reintentos a través de recargas de dominio)

• Sin conflictos de puertos ni de nombres de herramientas. Regístrate en ambos

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├──────────────────────────────┬──────────────────────────────┤
│  stdio launcher              │  (or direct HTTP clients)    │
│  ~/.unity-mcp/stdio.js       │                              │
│  resolves the session's      │                              │
│  project, reads its beacon   │                              │
│  Temp/UnityMcp_Endpoint.json │                              │
├──────────────────────────────┴──────────────────────────────┤
│           HTTP JSON-RPC (Port 5173, per project)            │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

Cada proyecto abierto ejecuta su propio servidor Node. El lanzador es la puerta de entrada compartida que enruta cada sesión al correcto.

Desarrollo

• Pruebas de Unity: Window > General > Test Runner (EditMode + PlayMode)

• Pruebas del lanzador: npm test en Server~/

• Changelog: CHANGELOG.md

Licencia

MIT. Consulta LICENSE.