Godot MCP Server

godot-mcp ermöglicht es MCP-Clients, Godot-Projekte zu inspizieren, zu validieren, zu testen, zu exportieren und abzufragen. Es unterstützt headless Godot-Befehle und optional Live-Zustand aus einem geöffneten Godot-Editor.

Voraussetzungen

• Node.js 18 oder neuer

• Godot 4.1 oder neuer, lokal installiert

• Ein Godot-Projekt, das project.godot enthält

Die Live-Editor-Tools erfordern zusätzlich das unten beschriebene MCP Bridge-Addon. Die übrigen Tools laufen headless.

Related MCP server: godot-ai-mcp

Installation

Aus einem lokalen Checkout

npm install
npm run build

Von npm (nach Veröffentlichung)

npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot

MCP-Client konfigurieren

Geben Sie immer den Projektpfad an. MCP-Desktop-Clients starten Server normalerweise in ihrem eigenen Arbeitsverzeichnis, daher ist die automatische Projekterkennung allein nicht zuverlässig.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Die entsprechenden Befehlszeilenoptionen sind:

godot-mcp --project /path/to/godot-project --godot /path/to/godot

GODOT_PATH/--godot ist nur optional, wenn die ausführbare Datei godot bereits im PATH ist. Unter Windows wird eine _console.exe-Datei bevorzugt.

Live-Editor-Tools aktivieren

1. Kopieren Sie godot-plugin/addons/mcp_bridge nach <your-project>/addons/mcp_bridge.

2. Öffnen Sie in Godot Projekt > Projekteinstellungen > Plugins und aktivieren Sie MCP Bridge.

3. Lassen Sie den Godot-Editor geöffnet, während Sie Live-Tools verwenden.

Die Brücke lauscht standardmäßig auf 127.0.0.1:7000. Setzen Sie mcp/plugin/port in project.godot, um dies zu überschreiben; der Server liest diese Einstellung aus dem oben konfigurierten Projekt. Schließen Sie addons/mcp_bridge/* von Produktions-Exportvoreinstellungen aus.

Tools

• Projekt und Export: get_project_settings, list_export_presets, export_project

• Tests und Validierung: run_tests, validate_scene, validate_script, run_scene, format_gdscript

• Szenen und Ressourcen: inspect_scene_tree, find_nodes, get_node_properties, get_node_connections, list_resources, get_resource_dependencies, resolve_path, get_resource_info

• Dokumentation: verify_api, get_help

• Live-Editor: get_editor_selection, get_open_scenes

Die meisten Tools geben ein strukturiertes JSON-Ergebnis mit success, data, errors, warnings und Zeitmetadaten zurück.

Entwicklung und Verifizierung

npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published

GitHub Actions führt sowohl die Node/MCP-Tests als auch die Godot-Addon-Prüfungen bei Pushes und Pull-Requests aus.

Release-Checkliste

1. Aktualisieren Sie die Version in package.json.

2. Führen Sie npm test, npm run test:godot und npm pack --dry-run aus.

3. Veröffentlichen Sie mit npm publish und erstellen Sie ein passendes GitHub-Release.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.