MCP de Unity ✨

Conecte su editor de Unity a LLM mediante el protocolo de contexto de modelo.

Unity MCP actúa como un puente, permitiendo que los asistentes de IA (como Claude y Cursor) interactúen directamente con tu editor de Unity a través de un cliente MCP (Protocolo de Contexto de Modelo) local. Proporciona a tu LLM herramientas para gestionar recursos, controlar escenas, editar scripts y automatizar tareas dentro de Unity.

Características principales 🚀

• 🗣️ Control de lenguaje natural: Instruya a su LLM para que realice tareas de Unity.

• 🛠️ Herramientas potentes: administre activos, escenas, materiales, guiones y funciones del editor.

• 🤖 Automatización: automatiza flujos de trabajo repetitivos de Unity.

• 🧩 Extensible: diseñado para funcionar con varios clientes MCP.

Su LLM puede utilizar funciones como:

• read_console : obtiene mensajes de la consola o la borra.

• manage_script : administra scripts de C# (crear, leer, actualizar, eliminar).

• manage_editor : controla y consulta el estado y la configuración del editor.

• manage_scene : Administra escenas (cargar, guardar, crear, obtener jerarquía, etc.).

• manage_asset : Realiza operaciones de activos (importar, crear, modificar, eliminar, etc.).

• manage_gameobject : Administra GameObjects: creación, modificación, eliminación, búsqueda y operaciones de componentes.

• execute_menu_item : ejecuta un elemento de menú a través de su ruta (por ejemplo, "Archivo/Guardar proyecto").

Cómo funciona 🤔

Unity MCP conecta sus herramientas mediante dos componentes:

1. Puente MCP de Unity: un paquete de Unity que se ejecuta dentro del editor (se instala mediante el Administrador de paquetes).

2. Servidor Unity MCP: Un servidor Python que se ejecuta localmente y se comunica entre Unity Bridge y su cliente MCP. (Se instala manualmente).

Flujo: [Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]

Instalación ⚙️

Nota: La configuración se mejora constantemente a medida que actualizamos el paquete. Vuelva a consultar si experimenta problemas de vez en cuando.

Prerrequisitos

• Git CLI: Para clonar el código del servidor. Descargar Git.

• Python: Versión 3.12 o posterior. Descargar Python.

• Unity Hub y Editor: Versión 2020.3 LTS o posterior. Descargar Unity.

• uv (administrador de paquetes de Python):

  pip install uv # Or see: https://docs.astral.sh/uv/getting-started/installation/

• Un cliente MCP:

  • Escritorio de Claude

  • Cursor

  • (Otros pueden trabajar con configuración manual)

Paso 1: Instalar el paquete Unity (Bridge)

1. Abra su proyecto de Unity.

2. Vaya a Window > Package Manager .

3. Haga clic en + -> Add package from git URL... .

4. Ingresar:

   https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge

5. Haga clic Add .

6. El servidor MCP debería instalarse automáticamente en su máquina como resultado de este proceso.

Paso 2: Configure su cliente MCP

Conecte su cliente MCP (Claude, Cursor, etc.) al servidor Python que instaló en el paso 1.

Opción A: Autoconfiguración (recomendada para Claude/Cursor)

1. En Unity, vaya a Window > Unity MCP .

2. Haga clic en Auto Configure Claude o Auto Configure Cursor .

3. Busca el indicador de estado verde 🟢 y la palabra "Conectado". (Esto intenta modificar automáticamente el archivo de configuración del cliente MCP) .

Opción B: Configuración manual

Si la configuración automática falla o utiliza un cliente diferente:

1. Encuentre el archivo de configuración de su cliente MCP. (Consulte la documentación del cliente).

   • Ejemplo de Claude (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

   • Ejemplo de Claude (Windows): %APPDATA%\Claude\claude_desktop_config.json

2. Edite el archivo para agregar/actualizar la sección mcpServers , utilizando las rutas exactas del Paso 1.

Ventanas:

(Recuerde reemplazar YOUR_USERNAME y utilizar barras invertidas dobles \)

macOS:

(Reemplace YOUR_USERNAME si usa ~/bin)

Linux:

(Reemplace SU_NOMBRE_DE_USUARIO)

Uso ▶️

1. Abra su proyecto de Unity. El puente Unity MCP (paquete) debería conectarse automáticamente. Compruebe el estado en Ventana > Unity MCP.

2. Inicie su cliente MCP (Claude, Cursor, etc.). Debería iniciar automáticamente el servidor Unity MCP (Python) con la configuración del paso 3 de instalación.

3. ¡Interactúa! Las herramientas de Unity ya deberían estar disponibles en tu cliente MCP.

   Ejemplo de solicitud: Create a 3D player controller.

Contribuyendo 🤝

¡Ayude a mejorar Unity MCP!

1. Bifurcar el repositorio principal.

2. Crea una rama ( feature/your-idea o bugfix/your-fix ).

3. Realizar cambios

4. Confirmar (oferta: agregar nueva característica interesante).

5. Empuja tu rama.

6. Abra una solicitud de extracción contra la rama maestra.

Solución de problemas ❓

• Unity Bridge no se ejecuta ni se conecta:

  • Asegúrese de que el Editor de Unity esté abierto.

  • Compruebe la ventana de estado: Ventana > Unity MCP.

  • Reiniciar Unity.

• El cliente MCP no se conecta/el servidor no se inicia:

  • Verificar la ruta del servidor: Verifique la ruta --directory en la configuración JSON de su cliente MCP. Debe coincidir exactamente con la ubicación donde clonó el repositorio de UnityMCP en el paso 1 de la instalación (p. ej., .../Programs/UnityMCP/UnityMcpServer/src).

  • Verificar uv: asegúrese de que uv esté instalado y funcionando (pip show uv).

  • Ejecutar manualmente: intente ejecutar el servidor directamente desde la terminal para ver los errores: # Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py

  • Permisos (MacOS/Linux): Si instaló el servidor en una ubicación del sistema como /usr/local/bin, asegúrese de que el usuario que ejecuta el cliente MCP tenga permiso para ejecutar uv y acceder a los archivos allí. Instalar en ~/bin podría ser más sencillo.

• Error de configuración automática:

  • Utilice los pasos de configuración manual. Es posible que la configuración automática no tenga permisos para escribir en el archivo de configuración del cliente MCP.

¿Sigues atascado? Abre un problema .

Licencia 📜

Licencia MIT. Véase el archivo LICENSE .

Contacto 👋

• X/Twitter: @justinpbarnett

Agradecimientos 🙏

Gracias a los colaboradores y al equipo de Unity.