MCP para Unity — Guía de Instalación y Configuración

UNITY_MCP_SETUP.md

MCP para Unity — Guía de Instalación y Configuración

Guía paso a paso para conectar un agente IA (GitHub Copilot en VS Code) con el Unity Editor a través de MCP (Model Context Protocol). Esto permite que la IA cree GameObjects, modifique escenas, lea logs de consola, ejecute tests y más — todo desde VS Code.

Requisitos Previos

Requisito	Versión mínima	Verificar con
Unity	2021.3 LTS+	Hub de Unity
Python	3.10+	python --version
uv (package manager)	Cualquiera	uv --version
VS Code	1.99+	code --version
GitHub Copilot Extension	Última	VS Code Extensions

Paso 1 — Instalar Python (si no lo tienes)

Descargar desde https://python.org/downloads/windows/ o instalar desde Microsoft Store buscando "Python 3.10" o superior.

Verificar:

python --version
# Debe mostrar Python 3.10+

Paso 2 — Instalar uv (UV Package Manager)

El servidor MCP de Unity requiere uv para gestionar sus dependencias Python.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Esto instala uv en %USERPROFILE%\.local\bin. Tras la instalación, reiniciar la terminal o añadir al PATH manualmente:

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

Verificar:

uv --version

IMPORTANTE: pip install uv NO es suficiente. Unity busca el binario standalone de uv en el PATH del sistema, no el wrapper de pip.

Paso 3 — Añadir unity-mcp al proyecto Unity

En el archivo Packages/manifest.json, añadir esta línea dentro de "dependencies":

"com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main"

Ejemplo:

{
  "dependencies": {
    "com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main",
    "com.unity.inputsystem": "1.11.2",
    ...
  }
}

Alternativamente, desde Unity: Window > Package Manager > + > Add package from git URL... y pegar:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Al abrir Unity, el paquete se descargará automáticamente.

Paso 4 — Iniciar el servidor MCP en Unity

1. Abrir Unity con el proyecto
2. Ir a Window > MCP for Unity
3. Se abrirá la ventana de MCP Setup (la primera vez verificará Python y uv)
4. Si todo está verde (Python ✅, UV ✅), click en Start Server
5. Verificar que aparezca:
   • 🟢 Session Active (NombreDelProyecto)
   • Una terminal externa con logs del servidor FastMCP

El servidor escucha en http://127.0.0.1:8080/mcp.

Paso 5 — Activar Auto-Start (RECOMENDADO)

Para que el servidor MCP se inicie automáticamente cada vez que abres Unity:

1. En la ventana MCP for Unity, ir a la pestaña Advanced
2. Activar el toggle "Auto-Start on Editor Load"
3. Esto guarda la preferencia en EditorPrefs (MCPForUnity.AutoStartOnLoad)

Con esta opción activa, no necesitas hacer nada manualmente — el servidor se levanta solo al abrir Unity.

Paso 6 — Configurar VS Code para conectarse al MCP

6.1 Crear .vscode/mcp.json

En la raíz del proyecto, crear el archivo .vscode/mcp.json:

{
  "servers": {
    "unity": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

6.2 Configurar desde Unity (alternativa)

En la ventana MCP for Unity:

1. En Client Configuration, seleccionar VSCode GitHub Copilot del dropdown
2. Click en Configure
3. Esto genera la configuración automáticamente

Paso 7 — Añadir instrucciones para Copilot

7.1 Instrucciones generales (.github/copilot-instructions.md)

Añadir al final del archivo existente (o crear uno nuevo):

## MCP para Unity (Server de Unity Editor)

Este proyecto tiene un servidor MCP (`unity-mcp` de CoplayDev) conectado al Unity Editor en `http://127.0.0.1:8080/mcp`.

**Cuándo usar herramientas MCP**:
- Crear, modificar o eliminar GameObjects en la escena activa
- Añadir o quitar componentes de GameObjects
- Consultar la jerarquía de la escena
- Leer logs de la consola de Unity
- Ejecutar tests desde el Editor
- Operaciones de escena que normalmente harías manualmente en Unity

**Cuándo NO usar MCP** (usar edición de archivos normal):
- Escribir o modificar scripts C# (editar archivos directamente)
- Crear o editar ScriptableObjects como archivos .asset
- Modificar configuración del proyecto (ProjectSettings/)

**Reglas**:
- El Unity Editor debe estar abierto con el servidor MCP corriendo
- Los GameObjects se referencian por ruta de jerarquía: `Parent/Child`
- Verificar el estado de la escena via MCP antes de hacer suposiciones
- Preferir operaciones MCP sobre escribir scripts de editor para tareas únicas

7.2 Instrucciones para archivos C# (.github/instructions/unity.instructions.md)

Crear el archivo con frontmatter YAML:

---
applyTo: "**/*.cs"
---

# C# Unity Guidelines

- Seguir convenciones de naming de Unity (PascalCase para métodos públicos)
- Para operaciones de escena (crear/modificar GameObjects, componentes), usar herramientas MCP del servidor Unity en lugar de escribir scripts de Editor

Adaptar con las convenciones específicas de tu proyecto.

Paso 8 — Verificar la conexión

1. Abrir VS Code en el proyecto
2. Abrir Copilot Chat (Ctrl+Shift+I)
3. Cambiar al modo Agent (dropdown en la parte superior del chat)
4. Verificar que el servidor "unity" aparece en la lista de herramientas MCP (icono 🔧)
5. Probar con un prompt: "Lista los GameObjects de la escena activa"

Si Copilot puede leer la jerarquía de la escena, todo está funcionando.

Troubleshooting

Problema	Solución
Unity no detecta uv	Instalar con el script oficial de Astral (Paso 2), NO con pip install uv. Reiniciar Unity después
El servidor no arranca	Verificar Python 3.10+ y uv en PATH. Revisar la ventana MCP Setup en Unity
Copilot no muestra herramientas MCP	Verificar que .vscode/mcp.json existe y el servidor está corriendo. Recargar VS Code (Ctrl+Shift+P → "Reload Window")
"Missing MCPForUnity Config" en Unity	Seleccionar "VSCode GitHub Copilot" como Client y click en Configure
Puerto 8080 en conflicto	Cambiar el puerto en la ventana MCP for Unity (Advanced > HTTP URL) y actualizar .vscode/mcp.json
Copilot no conecta al MCP	Abrir paleta de comandos (Ctrl+Shift+P) → "MCP: List Servers" → verificar que "unity" está "started"

Herramientas MCP disponibles

Una vez conectado, el agente puede usar ~26+ herramientas como:

• manage_gameobject — Crear, modificar, eliminar GameObjects
• manage_components — Añadir/quitar componentes
• manage_scene — Jerarquía, cargar/guardar escenas
• manage_material — Crear y modificar materiales
• manage_prefabs — Gestionar prefabs
• manage_asset — Buscar y gestionar assets
• read_console — Leer logs de Unity
• run_tests — Ejecutar tests
• manage_editor — Controlar Play Mode, compilación

Resumen de archivos necesarios

Proyecto/
├── .vscode/
│   └── mcp.json                              ← Conexión MCP para VS Code
├── .github/
│   ├── copilot-instructions.md               ← Instrucciones generales para Copilot
│   └── instructions/
│       └── unity.instructions.md             ← Instrucciones para archivos .cs
└── Packages/
    └── manifest.json                         ← Referencia a com.coplaydev.unity-mcp

Referencias

• unity-mcp (CoplayDev)
• VS Code — MCP Configuration
• VS Code — Custom Instructions
• Model Context Protocol