Servidor MCP de Unity

Chino | English

Plugin para el Editor de Unity que expone las capacidades del Editor de Unity a agentes de IA externos mediante MCP (Model Context Protocol).

Los agentes (como Kiro, Cursor, Claude Desktop) pueden conectarse al Editor de Unity a través del protocolo MCP estándar para invocar funciones del editor.

Características

Transporte HTTP transmitible — Basado en la especificación MCP 2025-03-26, punto final HTTP único
Ejecución en proceso — No requiere procesos externos de Node.js/Python, se inicia directamente dentro del Editor
Sistema de herramientas extensible — Implemente la interfaz IMcpTool para registrar nuevas herramientas, sin modificar el código central
Recuperación automática tras recarga de dominio — El servicio se reinicia automáticamente al entrar/salir del modo PlayMode

Herramientas integradas

Herramienta	Categoría	Función
`console_getLogs`	debug	Obtiene las últimas N entradas del registro de la consola de Unity
`debug_getStackTrace`	debug	Obtiene la pila completa del último Error/Excepción
`debug_getPerformanceStats`	debug	Obtiene métricas de rendimiento como FPS, DrawCalls, uso de memoria, etc.
`debug_screenshot`	debug	Captura una imagen de la vista Game/Scene (PNG en base64)
`menu_execute`	editor	Ejecuta un elemento del menú de Unity por su ruta
`playmode_control`	editor	Entra/sale/consulta el estado del modo PlayMode
`editor_getSelection`	editor	Obtiene información sobre el GameObject y el Asset seleccionados actualmente
`editor_getHierarchy`	editor	Obtiene la estructura del árbol de GameObjects de la escena (profundidad limitada)
`editor_getProjectStructure`	editor	Obtiene la estructura del directorio Assets (profundidad limitada)
`editor_getInspector`	editor	Obtiene los valores de los campos serializados del objeto seleccionado en el Inspector
`build_compile`	build	Dispara la compilación de scripts y devuelve el resultado
`build_getCompileErrors`	build	Obtiene la lista actual de errores de compilación
`build_runTests`	build	Ejecuta las pruebas del Unity Test Runner y devuelve el resultado

Instalación

Instalación mediante URL de Git (Recomendado)

Unity Editor → Window → Package Manager → + → Add package from git URL
Ingrese la siguiente URL:

https://github.com/yangfch3/Unity-MCP-Server.git

O edite directamente el archivo Packages/manifest.json del proyecto anfitrión:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

Instalación desde ruta local

Clone este repositorio
Unity Editor → Window → Package Manager → + → Add package from disk
Seleccione el archivo package.json en la raíz de este repositorio

O añada lo siguiente en Packages/manifest.json:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "file:../../path/to/unity-mcp"
  }
}

Actualizaciones de versión

Una vez instalado mediante URL de Git, UPM bloqueará el hash de commit actual en el archivo packages-lock.json del proyecto anfitrión. No se actualizará automáticamente en el futuro.

Si desea bloquear una versión específica, puede añadir un Git Tag al final de la URL:

https://github.com/yangfch3/Unity-MCP-Server.git#v0.1.0

Configuración correspondiente en Packages/manifest.json:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git#v0.1.0"
  }
}

Si no se incluye un Tag, se seguirá el commit más reciente de la rama predeterminada:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

Al actualizar la versión, modifique el sufijo #tag en manifest.json con el nuevo número de versión, o vuelva a realizar "Add package from git URL" en la interfaz gráfica de UPM ingresando la URL con el nuevo Tag.

Uso

Iniciar el servicio

Unity Editor → Window → MCP Server
Configure el puerto (predeterminado 8090) y haga clic en Start
Copie el JSON de configuración del panel

Configurar el Agente

Añada el siguiente contenido al archivo de configuración MCP del agente (por ejemplo, mcp.json):

{
  "mcpServers": {
    "unity-mcp": {
      "url": "http://localhost:8090/"
    }
  }
}

Extensión: Añadir herramientas personalizadas

Implemente la interfaz IMcpTool y colóquela en cualquier ensamblado del Editor; el servicio la detectará y registrará automáticamente al iniciarse:

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityMcp.Editor;

public class MyCustomTool : IMcpTool
{
    public string Name => "my_custom_tool";
    public string Category => "custom";
    public string Description => "我的自定义工具";
    public string InputSchema => "{\"type\":\"object\",\"properties\":{}}";

    public Task<ToolResult> Execute(Dictionary<string, object> parameters)
    {
        return Task.FromResult(ToolResult.Success("Hello from custom tool!"));
    }
}

Requisitos

Unity 2022.3+
Solo entorno de Editor, no afecta a las compilaciones en tiempo de ejecución

Contribución

La participación en el desarrollo de este proyecto es bienvenida, consulte CONTRIBUTING.md para más detalles.

Licencia

MIT

Unity MCP Server