Servidor MCP de Unity

Chino | English

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

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

Filosofía

Este plugin se posiciona como una capa de percepción de Unity + cadena de herramientas de diagnóstico para agentes de IA:

• Percepción primero — Prioriza la cobertura de escenarios de alta frecuencia como "leer el estado de la escena, obtener contexto, diagnóstico asistido", permitiendo que el agente comprenda completamente el estado actual del proyecto y ayude en la toma de decisiones de desarrollo.

• Escritura estructurada — Proporciona capacidades de escritura seguras y auditables (como modificar propiedades, añadir/eliminar nodos), pero no busca cubrir todas las interacciones de la GUI de Unity Editor.

• No reemplaza al editor — El objetivo es mejorar la eficiencia de la colaboración entre el ingeniero y el agente, no trasladar todas las operaciones del Editor a un cuadro de diálogo.

Related MCP server: MCP Unity

Características

• Transporte HTTP con streaming — 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 — Implementa la interfaz IMcpTool para registrar nuevas herramientas, sin modificar el código central.

• Recuperación automática tras Domain Reload — El servicio se reinicia automáticamente después de entrar/salir del PlayMode.

Herramientas integradas

Para obtener una descripción completa de los parámetros y ejemplos de uso, consulte la documentación detallada de herramientas.

Herramientas de depuración

Herramientas del Editor

Consulta (Query)

Mutación (Mutation)

Proyecto (Project)

Activos (Asset)

Herramientas de compilación (Build)

Herramientas de código (Experimental, solo Unity 2022 Mono)

Debe activarse manualmente en el panel Window → MCP Server. Consulte la documentación detallada de herramientas.

Instalación

Instalación mediante Git URL (Recomendado)

1. Unity Editor → Window → Package Manager → + → Add package from git URL

2. Introduzca 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

1. Clone este repositorio

2. Unity Editor → Window → Package Manager → + → Add package from disk

3. 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

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

Si necesita 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.3.0

Configuración correspondiente en Packages/manifest.json:

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

Si no se incluye un Tag, se seguirá el último commit 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 añadir el paquete desde la URL con el nuevo Tag en la GUI de UPM.

Uso

Iniciar el servicio

1. Unity Editor → Window → MCP Server

2. Configure el puerto (por defecto 8090) y haga clic en Start

3. 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 descubrirá 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 Editor, no afecta a las compilaciones en tiempo de ejecución (runtime)

Contribuir

Le invitamos a participar en el desarrollo de este proyecto, consulte CONTRIBUTING.md para más detalles.

Licencia

MIT