Godot MCP Server

Ein umfassender FastMCP-Server für die Godot-4.x-Spieleentwicklung. Bietet Werkzeuge für KI-gestützte Arbeitsabläufe: Projektverwaltung, Dateioperationen, Asset-Erkennung, GDScript-Entwicklung und optionale Godot-Ausführung.

Beitragen · Sicherheit

Sicherheitsmodell: Alle Godot-Projekte, Dateischreibvorgänge und Asset-Library-Downloads sind auf ein einzelnes Arbeitsbereichsverzeichnis auf Ihrem Rechner beschränkt (Standard: ~/godot-games). Der Server lehnt Pfade außerhalb dieses Verzeichnisbaums ab. Siehe Einrichtung des Arbeitsbereichs.

Codeausführung: godot_run_game und godot_execute_script erfordern GODOT_MCP_ALLOW_GODOT_EXEC in der Serverumgebung. Die mitgelieferten MCP-JSON-Konfigurationen setzen sie auf 1, sodass diese Werkzeuge nach dem Kopieren und Einfügen funktionieren. Wenn Sie python godot_mcp_server.py ohne diese Umgebungsvariable ausführen, bleibt die Ausführung deaktiviert, bis Sie sie exportieren. Um eine IDE-Installation abzusichern, entfernen Sie die Variable oder setzen Sie sie auf 0. Siehe Godot-Ausführung (Umgebung).

HTTP-Transport: Die Bindung an 0.0.0.0 oder :: macht den MCP-Server auf allen Netzwerkschnittstellen verfügbar; bevorzugen Sie 127.0.0.1, sofern Sie keine Firewall oder VPN verwenden.

Symlinks: GODOT_MCP_ROOT wird unter Auflösung von Symlinks ausgewertet; zeigen Sie ihn auf ein echtes Verzeichnis, das Sie kontrollieren.

Funktionen

Projektverwaltung

• Godot-Projekte automatisch erkennen (project.godot); alle Projekte im Arbeitsbereich auflisten (godot_list_projects)

• Neue Projekte im Arbeitsbereich erstellen (godot_create_project)

• Projekteinstellungen und -konfiguration parsen; Autoloads und Editor-Plugin-Status auflisten (für Plugins schreibgeschützt)

• Projektcache nach Änderungen aktualisieren

Dateioperationen

• Szenen (.tscn), Skripte (.gd) und Ressourcen (.tres) lesen/schreiben

• Neue Skripte, Szenen und Ressourcen aus Vorlagen erstellen

• Bestehende Dateien durch Inhaltsersetzung bearbeiten

• Szenen- und Skriptsyntax validieren

Codegenerierung

• CharacterBody2D/3D-Bewegungssteuerungen

• State-Machine-Muster

• Benutzerdefinierte Ressourcen

• Node-Skripte mit Signalen/Exports

Asset-Verwaltung

• Assets nach Erweiterung, Muster oder Glob finden

• Ungenutzte Assets finden

• Dateiinhalte mit Regex durchsuchen

• In der Godot Asset Library suchen und herunterladen

• Godot-Repos auf GitHub durchsuchen

Laufzeitintegration

• Godot-Executable finden

• Godot-Version prüfen

• Spiel headless ausführen

• GDScript-Code ausführen

• Godot-Protokolle lesen

• Konfiguration des Dateiüberwachers

Related MCP server: Godot MCP

Installation

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

Konsolen-Einstiegspunkt (nach pip install -e .): godot-mcp-server (identisch mit python godot_mcp_server.py).

Einrichtung des Arbeitsbereichs (erforderlich)

Der MCP-Server arbeitet nur mit Godot-Projekten, die sich unter einem einzigen Wurzelordner befinden. Dadurch wird verhindert, dass Assistenten beliebige Pfade auf Ihrem System lesen oder schreiben.

1. Standardordner erstellen (einmal pro Rechner):

   mkdir -p ~/godot-games

2. Jedes Godot-Spiel dort ablegen – jedes Spiel ist ein eigenes Unterverzeichnis, das project.godot enthält, zum Beispiel:

   ~/godot-games/
     my-platformer/     ← open this folder in your editor
       project.godot
       ...
     another-game/
       project.godot

3. Öffnen Sie Ihren IDE-Arbeitsbereich in ~/godot-games/.../your-game (oder in einem übergeordneten Ordner unter ~/godot-games), damit der MCP-Prozess project.godot aus dem aktuellen Arbeitsverzeichnis finden kann.

4. Benutzerdefinierter Speicherort: Legen Sie vor dem Start des Servers einen absoluten Pfad fest:

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   python godot_mcp_server.py

   Fügen Sie in Cursor / Claude / anderen MCP-Konfigurationen env hinzu:

   "env": {
     "GODOT_MCP_ROOT": "/path/to/your/godot-games"
   }

   Wenn nicht gesetzt, lautet der Standard $HOME/godot-games. Der Server erstellt dieses Verzeichnis beim Start, falls es nicht existiert.

5. Zur Laufzeit prüfen: Rufen Sie das Werkzeug godot_get_workspace auf oder lesen Sie die Ressource project://workspace, um den aktiven Arbeitsbereichspfad zu sehen.

Wenn Werkzeuge melden, dass kein Projekt gefunden wurde, liegt Ihr aktuelles Arbeitsverzeichnis (cwd) wahrscheinlich außerhalb des Arbeitsbereichs, oder project_path zeigt außerhalb von GODOT_MCP_ROOT.

Godot-Ausführung (Umgebung)

Das Ausführen des Spiels oder das Ausführen von GDScript führt Code mit Ihrem Benutzerkonto aus (genau wie beim Start von Godot aus einem Terminal). Der Server aktiviert godot_run_game / godot_execute_script nur, wenn GODOT_MCP_ALLOW_GODOT_EXEC auf einen akzeptierten „Ein“-Wert gesetzt ist.

Mitgelieferte MCP-JSON-Konfigurationen (Standard: ja): Jedes Beispiel-JSON in diesem Repository (mcp_config.json, mcp_config.cursor.json, usw.) enthält:

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

Wenn Sie also eine davon in Ihre IDE kopieren, ist die Ausführung erlaubt, ohne weitere Schritte. Fügen Sie weitere Schlüssel (z. B. GODOT_MCP_ROOT) in dasselbe env-Objekt ein.

CLI ohne MCP-Konfiguration: Wenn Sie python godot_mcp_server.py ausführen, wird diese Variable nicht gesetzt; die Ausführungswerkzeuge bleiben blockiert, bis Sie export GODOT_MCP_ALLOW_GODOT_EXEC=1 ausführen (oder ein Wrapper-Skript verwenden).

Strengere Konfigurationen: Entfernen Sie GODOT_MCP_ALLOW_GODOT_EXEC aus env oder setzen Sie ihn auf 0 / false / no / off, und starten Sie dann den MCP-Client neu.

Akzeptierte „Ein“-Werte: 1, true, yes, on (Groß-/Kleinschreibung wird nicht beachtet). Rufen Sie godot_get_workspace auf und prüfen Sie godot_exec_allowed, um dies zu bestätigen.

Verwendung

CLI (stdio – für Claude Code/Cursor)

python godot_mcp_server.py

HTTP-Server

python godot_mcp_server.py --transport http --port 8765

Konfiguration

Setzen Sie GODOT_MCP_ROOT in der env des MCP-Servers, wenn Sie nicht den Standard ~/godot-games verwenden. Siehe Einrichtung des Arbeitsbereichs. Die unten mitgelieferten Ausschnitte enthalten GODOT_MCP_ALLOW_GODOT_EXEC; siehe Godot-Ausführung (Umgebung).

Pfad zum Server: Die Beispiele verwenden "args": ["godot_mcp_server.py"] und gehen davon aus, dass der MCP-Prozess mit seinem Arbeitsverzeichnis in dem Ordner läuft, der das Skript enthält (z. B. wenn Sie dieses Repository geklont haben). Wenn der Server nicht startet, ersetzen Sie das durch den absoluten Pfad zu godot_mcp_server.py auf Ihrem Rechner.

In Ihrem Editor installieren

Erweitern Sie einen Abschnitt und fügen Sie das JSON in die Datei ein, die Ihr Werkzeug erwartet. Derselbe godot-Serverblock ist im Repository als mcp_config.*.json zum Kopieren und Einfügen vorhanden.

macOS / Linux (Projekt- oder Benutzerkonfiguration) – Einstellungen → MCP → Neuen globalen MCP-Server hinzufügen oder erstellen Sie .cursor/mcp.json in einem Projektstamm:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Windows – wenn python für den MCP-Host nicht im PATH ist, verwenden Sie den Launcher oder den vollständigen Pfad zu python.exe, und bevorzugen Sie einen absoluten Pfad in args:

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Fügen Sie GODOT_MCP_ROOT in env ein, wenn Sie nicht ~/godot-games verwenden (siehe Einrichtung des Arbeitsbereichs).

Verwenden Sie die MCP-/Agenteneinstellungen, die Ihre VS-Code-Version bereitstellt (oft Einstellungen → MCP oder ein Projekt-.vscode/mcp.json, je nach Version und Erweiterungen). Fügen Sie dieselbe Struktur wie bei Cursor ein:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Verwenden Sie einen absoluten Pfad in args, wenn der Arbeitsbereichsordner nicht das Repository-Stammverzeichnis ist.

Bearbeiten Sie die App-Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Starten Sie Claude Desktop nach dem Speichern neu.

Fügen Sie dies in ~/.claude/settings.json ein (oder verwenden Sie claude mcp add, wenn Ihr CLI dies unterstützt – prüfen Sie claude mcp --help):

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

macOS / Linux: Bearbeiten Sie ~/.codeium/windsurf/mcp_config.json oder verwenden Sie CMD+SHIFT+P → „Windsurf: MCP-Server konfigurieren“.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

Fügen Sie dies in Roos MCP-Einstellungen ein (Projekt oder global), in derselben JSON-Struktur wie oben. Repository-Kopie: roo_code_mcp.json.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}

Minimale stdio-Konfiguration – identisch mit mcp_config.json in diesem Repository:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

Grenzen (DoS / Missbrauch)

• Regex-Suche (godot_search_content): Die Musterlänge ist begrenzt; die Trefferliste ist begrenzt; Dateien größer als 2 MiB werden übersprungen. Bösartige Regex kann trotzdem teuer sein – halten Sie die Muster einfach.

• Asset-Zip-Download: Maximale Downloadgröße, unkomprimierte Größe pro Datei, gesamte unkomprimierte Größe und Dateianzahl werden vor der Extraktion durchgesetzt (siehe Konstanten am Anfang von godot_mcp_server.py).

• Asset-Library-IDs: asset_id für godot_get_asset_info / godot_download_asset darf nur aus numerischen Ziffern bestehen.

HTTP-Modus (Remote)

Verwenden Sie Loopback, außer Sie wissen, was Sie tun:

python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765

Die Bindung an alle Schnittstellen (--host 0.0.0.0) protokolliert eine Warnung und macht MCP in Ihrem LAN ohne Authentifizierung verfügbar.

Verwenden Sie dann serverUrl anstelle von command:

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

Führen Sie für dasselbe Projekt nur einen Transport aus (stdio oder HTTP), nicht beide gleichzeitig, um widersprüchliche MCP-Sitzungen zu vermeiden.

Werkzeugreferenz

40 MCP-Werkzeuge sind in godot_mcp_server.py registriert (suchen Sie nach @mcp.tool). Zusammenfassung:

Editor-Plugins: Dieser Server schreibt kein [editor_plugins] in project.godot (vermeidet Konflikte mit einem geöffneten Editor). Installieren Sie Addons über die obigen Tools; der Benutzer aktiviert Plugins in Projekteinstellungen → Plugins in Godot; verwenden Sie godot_list_editor_plugins zur Überprüfung.

Ressourcen

Beispiele

Plattformer-Spieler erstellen

# Using template
create_code_template("character_body_2d", "Player")

Assets finden

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

Asset-Bibliothek durchsuchen

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

Spiel headless ausführen

Erfordert GODOT_MCP_ALLOW_GODOT_EXEC (in den mitgelieferten MCP-JSON-Konfigurationen enthalten).

run_game(headless=True, quit_after_seconds=30)

Anforderungen

• Python 3.10+

• Abhängigkeiten: fastmcp, urllib3 (siehe pyproject.toml)

Entwicklung

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

Kontinuierliche Integration läuft auf Python 3.10–3.14 (siehe .github/workflows/ci.yml). Dependabot eröffnet wöchentlich PRs für pip und GitHub Actions.

Optional: pip install pre-commit && pre-commit install verwendet .pre-commit-config.yaml.

Auf GitHub veröffentlichen

1. Erstellen Sie ein leeres Repository auf GitHub (kein README/Lizenz, wenn Sie diese bereits lokal haben), z. B. godot-mcp-server.

2. Fügen Sie das Remote hinzu und pushen Sie:

cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main

Oder mit GitHub CLI: gh repo create godot-mcp-server --public --source=. --remote=origin --push

Nach dem ersten Push läuft die CI bei jedem Push und jeder PR. Ersetzen Sie sterion66 in den README-Badge-URLs, wenn Sie ein anderes Konto oder eine andere Organisation verwenden.

Lizenz

MIT