Unity MCP Server

Chinesisch | Englisch

Ein Unity Editor-Plugin, das die Funktionen des Unity Editors über das MCP (Model Context Protocol) für externe KI-Agenten verfügbar macht.

Agenten (wie Kiro, Cursor, Claude Code) können sich über das Standard-MCP-Protokoll mit dem Unity Editor verbinden und Editor-Funktionen aufrufen.

Konzept

Dieses Plugin ist als Unity-Wahrnehmungsebene + Diagnose-Toolchain für KI-Agenten positioniert:

• Wahrnehmung zuerst — Priorisiert die Abdeckung häufiger Szenarien wie "Szenenstatus lesen, Kontext abrufen, Diagnose unterstützen", damit der Agent den aktuellen Projektstatus vollständig verstehen und Entwicklungsentscheidungen unterstützen kann.

• Strukturiertes Schreiben — Bietet sichere, prüfbare Schreiboperationen (z. B. Ändern von Eigenschaften, Hinzufügen/Löschen von Knoten), strebt jedoch nicht die Abdeckung aller Interaktionen der Unity Editor GUI an.

• Kein Ersatz für den Editor — Das Ziel ist es, die Effizienz der Zusammenarbeit zwischen Ingenieuren und Agenten zu steigern, anstatt alle Editor-Operationen in ein Dialogfeld zu verlagern.

Related MCP server: MCP Unity

Funktionen

• Streamable HTTP-Übertragung — Basiert auf der MCP-Spezifikation vom 26.03.2025, einzelner HTTP-Endpunkt

• In-Process-Ausführung — Kein externer Node.js/Python-Prozess erforderlich, startet direkt im Editor

• Erweiterbares Tool-System — Implementieren Sie einfach das IMcpTool-Interface, um neue Tools zu registrieren, ohne den Kerncode zu ändern

• Automatische Wiederherstellung bei Domain Reload — Der Dienst startet nach dem Betreten/Verlassen des PlayMode automatisch neu

Integrierte Tools

Die vollständige Parameterbeschreibung und Anwendungsbeispiele finden Sie in der ausführlichen Tool-Dokumentation.

Debug-Tools

Editor-Tools

Query (Abfrage)

Mutation (Änderung)

Project (Projekt)

Asset (Vermögenswerte)

Build-Tools

Code-Tools (Experimentell, nur Unity 2022 Mono)

Muss im Fenster "Window → MCP Server" manuell aktiviert werden. Siehe ausführliche Tool-Dokumentation.

Installation

Installation per Git URL (Empfohlen)

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

2. Geben Sie die folgende URL ein:

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

Oder bearbeiten Sie direkt die Packages/manifest.json des Host-Projekts:

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

Installation über lokalen Pfad

1. Klonen Sie dieses Repository

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

3. Wählen Sie die package.json im Stammverzeichnis dieses Repositorys

Oder fügen Sie Folgendes in Packages/manifest.json hinzu:

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

Versions-Updates

Nach der Installation über die Git URL wird der aktuelle Commit-Hash in der packages-lock.json des Host-Projekts gesperrt. Es erfolgt kein automatisches Update.

Um eine bestimmte Version zu sperren, können Sie am Ende der URL ein Git-Tag anhängen:

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

Entsprechende Packages/manifest.json-Konfiguration:

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

Ohne Tag wird der neueste Commit des Standard-Branch verfolgt:

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

Um die Version zu aktualisieren, ändern Sie das #tag-Suffix in der manifest.json auf die neue Versionsnummer oder fügen Sie das Paket im UPM GUI erneut über "Add package from git URL" mit der neuen Tag-URL hinzu.

Verwendung

Dienst starten

1. Unity Editor → Window → MCP Server

2. Port einstellen (Standard 8090), auf Start klicken

3. Die Konfigurations-JSON aus dem Panel kopieren

Agent konfigurieren

Fügen Sie den folgenden Inhalt zur MCP-Konfigurationsdatei des Agenten hinzu (z. B. mcp.json):

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

Erweiterung: Eigene Tools hinzufügen

Implementieren Sie das IMcpTool-Interface und platzieren Sie es in einer beliebigen Editor-Assembly. Der Dienst erkennt und registriert es beim Start automatisch:

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!"));
    }
}

Anforderungen

• Unity 2022.3+

• Nur Editor-Umgebung, beeinträchtigt nicht den Runtime-Build

Mitwirken

Sie sind herzlich eingeladen, an der Entwicklung dieses Projekts mitzuwirken. Weitere Informationen finden Sie unter CONTRIBUTING.md.

Lizenz

MIT