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:
- Puente MCP de Unity: un paquete de Unity que se ejecuta dentro del editor (se instala mediante el Administrador de paquetes).
- 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:
Paso 1: Instalar el paquete Unity (Bridge)
- Abra su proyecto de Unity.
- Vaya a
Window > Package Manager . - Haga clic en
+ -> Add package from git URL... . - Ingresar:
https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
- Haga clic
Add . - El servidor MCP debería instalarse automáticamente en su máquina como resultado de este proceso.
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)
- En Unity, vaya a
Window > Unity MCP . - Haga clic en
Auto Configure Claude o Auto Configure Cursor . - 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:
- 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
- Edite el archivo para agregar/actualizar la sección
mcpServers , utilizando las rutas exactas del Paso 1.
Ventanas:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
"server.py"
]
}
// ... other servers might be here ...
}
}
(Recuerde reemplazar YOUR_USERNAME y utilizar barras invertidas dobles \)
macOS:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"/usr/local/bin/UnityMCP/UnityMcpServer/src",
"server.py"
]
}
// ... other servers might be here ...
}
}
(Reemplace YOUR_USERNAME si usa ~/bin)
Linux:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
"server.py"
]
}
// ... other servers might be here ...
}
}
(Reemplace SU_NOMBRE_DE_USUARIO)
Uso ▶️
- Abra su proyecto de Unity. El puente Unity MCP (paquete) debería conectarse automáticamente. Compruebe el estado en Ventana > Unity MCP.
- 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.
- ¡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!
- Bifurcar el repositorio principal.
- Crea una rama (
feature/your-idea o bugfix/your-fix ). - Realizar cambios
- Confirmar (oferta: agregar nueva característica interesante).
- Empuja tu rama.
- 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 .
Agradecimientos 🙏
Gracias a los colaboradores y al equipo de Unity.