Unity Code MCP Server

Herramienta potente para el Editor de Unity que otorga a los Agentes de IA la capacidad de realizar cualquier acción utilizando la API del Editor de Unity, como modificación de scripts, escenas, prefabs, assets, configuración y más.

GitHub

Prueba este MCPPatrocinado

Documentación

Unity Code MCP Server

Buscar en el proyecto Unity en vivo

Inspecciona escenas activas, componentes, assets, salida de consola, configuraciones, estado de Play Mode y valores en tiempo de ejecución desde un cliente MCP.

Ejecutar directamente dentro del Editor

Crea y modifica GameObjects, prefabs, ScriptableObjects, configuraciones de importación y otros assets de Unity ejecutando C# en el Editor.

Verificar con retroalimentación en tiempo de ejecución

Ejecuta pruebas en Edit Mode y Play Mode, entra en Play Mode, simula entrada del jugador, captura capturas de pantalla, lee registros de consola de Unity e inspecciona el estado del juego en vivo después de las acciones.

Ejemplo de flujo de trabajo de agente: Juega Pong en un bucle cerrado usando enter_play_mode, execute_csharp_script_in_unity_editor, play_unity_game y read_unity_console_logs para buscar el estado en tiempo de ejecución, ejecutar acciones de entrada, verificar el resultado y adaptar el siguiente movimiento. Play Pong game example

Ejemplo de flujo de trabajo real

Consulta el ejemplo completo de flujo de trabajo de ciudades y su transcripción.

Herramientas

execute_csharp_script_in_unity_editor

Realiza cualquier tarea ejecutando scripts C# generados en el contexto del Editor de Unity. Acceso completo a UnityEngine, APIs de UnityEditor y reflexión. Captura automáticamente registros, errores y valores de retorno.

read_unity_console_logs

Lee los registros de consola del Editor de Unity con límites de entrada configurables (1-1000, predeterminado 200)

run_unity_tests

Ejecuta pruebas de Unity a través de TestRunnerApi. Admite EditMode, PlayMode o ambos. Puede ejecutar todas las pruebas o filtrar por nombres de prueba totalmente calificados.

enter_play_mode

Entra en Play Mode de Unity, pausa el tiempo y regresa inmediatamente después de activar la transición. Diseñado para usarse antes de las herramientas de automatización de juego.

play_unity_game

Pausa temporalmente el tiempo, simula acciones de Input System configuradas, recopila registros y pausa nuevamente al finalizar.

get_unity_game_view_window_screenshot

Captura la vista de juego actual de Unity como una imagen sin enrutar la captura de pantalla a través de llamadas de entrada de juego.

exit_play_mode

Sale de Play Mode de Unity, reanuda el tiempo y regresa inmediatamente después de activar la transición.

get_unity_info

Devuelve información sobre el proyecto actual del Editor de Unity y la configuración de UnityCodeMcpServer.

Consideraciones de seguridad

Este paquete ejecuta código C# generado por LLM (incluido código de reflexión) con los mismos privilegios que el proceso del Editor de Unity. Eres responsable de asegurar tu entorno y de cualquier cambio o pérdida de datos causada por los scripts ejecutados.

Arquitectura

diagram
Diagrama de arquitectura: El paquete Unity Code MCP Server se ejecuta dentro del Editor de Unity y se comunica con un cliente MCP externo (como un agente LLM) a través de un puente STDIO respaldado por archivos.

Transporte STDIO

graph LR
    A["MCP Client<br/>AI Agent"] -->|STDIO| B["STDIO Bridge<br/>Python script"]
    B <-->|request/response files| C["Unity Code MCP Server<br/>Unity Editor"]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5

Inicio rápido

Requisitos

Unity 2022.3 LTS o superior (probado en 2022.3.62f3 y 6000.2.7f2)
uv (administrador de paquetes de Python) para el puente STDIO incluido: https://docs.astral.sh/uv/.

Instalación

Instala uv:
- Sigue las instrucciones en https://docs.astral.sh/uv/getting-started/installation
Instala Unity Code MCP Server desde Unity Package Manager. Abre Window > Package Manager, haz clic en el botón +, selecciona Add package from git URL... e ingresa:

https://github.com/Signal-Loop/UnityCodeMCPServer.git?path=Assets/Plugins/UnityCodeMcpServer

Configura la ubicación de instalación de habilidades. Abre Tools/UnityCodeMcpServer/Show or Create Settings, desplázate a la sección Skills y confirma o cambia el directorio de instalación. De forma predeterminada, las instalaciones por primera vez apuntan a .agents/skills/. Las habilidades se instalan y actualizan automáticamente cuando el paquete se instala o actualiza.

Primera ejecución

Configuración del cliente MCP

Abre tu proyecto de Unity. Unity inicia automáticamente el transporte respaldado por archivos y observa .unityCodeMcpServer/messages en la raíz del proyecto.
Configura tu cliente MCP para ejecutar el puente STDIO incluido.

STDIO

Ejemplo de configuración (usando uv para ejecutar el puente):

El puente unity-code-mcp-stdio reenvía el tráfico STDIO a Unity a través de .unityCodeMcpServer/messages.

{
  "mcpServers": {
    "unity-code-mcp-stdio": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/path/to/UnityProject/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
        "unity-code-mcp-stdio"
      ]
    }
  }
}

Configuración del servidor (Unity)

Accede a la configuración a través de Tools/UnityCodeMcpServer/Show or Create Settings.
Configura Verbose Logging para diagnósticos detallados y opcionalmente establece Input Actions Asset para play_unity_game.

El transporte respaldado por archivos intercambia archivos de solicitud y respuesta a través de .unityCodeMcpServer/messages en la raíz del proyecto de Unity.

Comandos de menú

General

Tools/UnityCodeMcpServer/Show or Create Settings — Abre el asset de configuración del servidor en el inspector

Habilidades del agente

Unity Code MCP Server incluye un conjunto de archivos de habilidades de agente de IA (documentos Markdown que enseñan a tu agente cómo usar las herramientas del servidor de manera efectiva). Estas habilidades se instalan automáticamente en el directorio de destino configurado cada vez que el paquete se instala o actualiza.

Instalación de habilidades

Abre la configuración del servidor: Tools/UnityCodeMcpServer/Show or Create Settings.
Desplázate a la sección Skills.
Elige el directorio de instalación del menú desplegable:

GitHub apunta a .github/skills/
Claude apunta a .claude/skills/
Agents apunta a .agents/skills/
Custom muestra un selector de carpetas para que puedas elegir cualquier directorio

El inspector muestra la etiqueta del directorio de destino actualmente seleccionado para que puedas verificar exactamente dónde se copiarán las habilidades.
La instalación y actualización del paquete copia las habilidades automáticamente.

Solo se copian archivos .md nuevos o modificados. Los archivos que ya están actualizados (coincidencia de hash de contenido) se omiten.

Habilidades incluidas

Habilidad	Descripción
`executing-csharp-scripts-in-unity-editor`	Enseña al agente cuándo y cómo usar `execute_csharp_script_in_unity_editor`, `read_unity_console_logs` y `run_unity_tests` juntos como un pipeline confiable. Cubre patrones prohibidos, bucles de depuración y patrones de scripting comunes.
`unity-game-player`	Enseña al agente cómo jugar y probar juegos de Unity en un bucle cerrado usando `enter_play_mode`, `play_unity_game`, `execute_csharp_script_in_unity_editor`, `read_unity_console_logs` y `exit_play_mode`. Cubre descubrimiento de escenas, sincronización de acciones basada en matemáticas y re-detección adaptativa.

Extensión (agregar herramientas)

Agrega Tools, Prompts, Resources o Async Tools implementando las interfaces relevantes (ITool, IToolAsync, IPrompt, IResource) en cualquier parte de tu código. El servidor las detectará y registrará automáticamente.

Herramienta síncrona

using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;

public class EchoTool : ITool
{
    public string Name => "echo";

    public string Description => "Echoes the input text back to the caller";

    public JToken InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                }
            },
            ""required"": [""text""]
        }");

    public ToolsCallResult Execute(JToken arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");

        return ToolsCallResult.TextResult($"Echo: {text}");
    }
}

Herramienta asíncrona

using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;
using System.Threading.Tasks;

public class DelayedEchoTool : IToolAsync
{
    public string Name => "delayed_echo";

    public string Description => "Echoes the input text after a specified delay (demonstrates async tool)";

    public JToken InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                },
                ""delayMs"": {
                    ""type"": ""integer"",
                    ""description"": ""Delay in milliseconds before echoing"",
                    ""default"": 1000
                }
            },
            ""required"": [""text""]
        }");

    public async Task<ToolsCallResult> ExecuteAsync(JToken arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");
        var delayMs = arguments.GetIntOrDefault("delayMs", 1000);

        await Task.Delay(delayMs);

        return ToolsCallResult.TextResult($"Delayed Echo (after {delayMs}ms): {text}");
    }
}

Contexto de ejecución de scripts

De forma predeterminada, el contexto de ejecución de scripts incluye los siguientes ensamblados:

Assembly-CSharp
Assembly-CSharp-Editor
System.Core
UnityEngine.CoreModule
UnityEditor.CoreModule

La configuración de Unity Code MCP Server (Assets/Plugins/UnityCodeMcpServer/Editor/Resources/UnityCodeMcpServerSettings.asset) permite configurar ensamblados adicionales para incluir en el contexto de ejecución de scripts. Esto es útil si tu proyecto tiene ensamblados que tus scripts generados necesitan referenciar.

Para agregar ensamblados adicionales, usa la sección 'Additional Assemblies' de la configuración.

Additional Assemblies

Puente STDIO

Consulta la documentación del puente en README_STDIO.md.

Pruebas

Las pruebas de Unity están en Assets/Tests/ y se pueden ejecutar a través de Unity Test Runner.

Problemas conocidos

Conflictos de GUID con archivos dll existentes en el proyecto

Unity Code MCP Server incluye archivos dll en su paquete. Si esos archivos ya están presentes en tu proyecto, es posible que veas conflictos de GUID. En nuestros casos de prueba no causa ningún problema, pero si encuentras problemas, por favor completa el issue: Issues. Eliminar dll duplicados de tu proyecto puede resolver los conflictos.

GUID [eb9c83041c7a89c46bb6e20eab4484df] for asset 'Packages/com.signal-loop.unitycodemcpserver/Editor/Bin/Microsoft.CodeAnalysis.CSharp.dll' conflicts with:
  '[Path to dll file in your project]/Microsoft.CodeAnalysis.CSharp.dll' (current owner)
We can't assign a new GUID because the asset is in an immutable folder. The asset will be ignored.

Licencia

MIT