godot-mcp-pilot

Сервер Model Context Protocol для Godot 4 — предоставьте ИИ-ассистентам (Claude, Cursor, Cline и др.) прямой контроль над вашими проектами Godot.

godot-mcp-pilot предоставляет операции движка Godot в качестве инструментов MCP, позволяя ИИ-ассистентам запускать редактор, запускать проекты, создавать и редактировать сцены, писать код на GDScript и проверять ресурсы — и все это с помощью естественного языка. Работает как для 2D, так и для 3D игр.

"Create a CharacterBody3D player scene with a Camera3D and collision"
"Run the project and show me any errors"
"Add a DirectionalLight3D to the scene"
"Create a 2D platformer with sprites and tilemaps"

Быстрый старт

1. Установка

npm install -g godot-mcp-pilot

Или используйте без установки:

npx godot-mcp-pilot

2. Запуск мастера настройки

npx godot-mcp-pilot setup
# or, if installed globally:
godot-mcp-pilot-setup

Мастер выполнит следующие действия:

• Автоматически обнаружит ваш бинарный файл Godot (проверяет папки Applications, Downloads, PATH)

• Спросит, какой ИИ-клиент вы используете

• Запишет конфигурацию в нужное место для этого клиента

Ручная настройка

Claude Code (CLI / расширение для IDE)

Важно: Claude Code считывает .mcp.json из той директории, в которой вы его запускаете. Файл должен находиться в папке вашего игрового проекта, а не в папке godot-mcp-pilot.

# From inside your game project directory:
claude mcp add godot -- npx godot-mcp-pilot

Это запишет .mcp.json в вашу текущую директорию. После этого всегда запускайте Claude Code из этой директории:

cd ~/games/my-platformer
claude

Если Godot не был обнаружен автоматически (например, вы не переместили его из ~/Downloads):

claude mcp add godot -e GODOT_PATH=/path/to/Godot.app/Contents/MacOS/Godot -- npx godot-mcp-pilot

Или создайте .mcp.json вручную в корне вашего игрового проекта:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Claude Desktop

Claude Desktop использует другой файл конфигурации — он не считывает .mcp.json.

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Затем закройте и снова откройте Claude Desktop.

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Обнаружение пути к Godot

Сервер автоматически ищет в следующих местах (в указанном порядке):

Если автоматическое обнаружение не сработало, установите GODOT_PATH на абсолютный путь к вашему исполняемому файлу Godot.

2D и 3D игры

godot-mcp-pilot одинаково хорошо работает как с 2D, так и с 3D. Используйте соответствующие типы узлов:

Примеры запросов:

"Create a 3D scene with a Node3D root, MeshInstance3D floor, and DirectionalLight3D"
"Add a CharacterBody3D with a CollisionShape3D using a CapsuleShape3D"
"Write a GDScript for 3D first-person movement"

Функции

Конфигурация

Устранение неполадок

"MCP server not connected" / инструменты не появляются

Claude Code: Файл .mcp.json должен находиться в директории, из которой вы запускаете claude. Откройте новый терминал, перейдите (cd) в папку вашего игрового проекта и запустите claude оттуда.

Claude Desktop: Убедитесь, что вы отредактировали правильный файл (claude_desktop_config.json, а не .mcp.json), а также полностью закрыли и снова открыли приложение.

Godot не найден

Явно установите GODOT_PATH в блоке env конфигурации. В macOS, если вы скачали Godot, но не переместили его:

GODOT_PATH=/Users/yourname/Downloads/Godot.app/Contents/MacOS/Godot

Чтобы найти, где находится Godot:

# macOS / Linux
find ~/Downloads ~/Applications /Applications -name "Godot" -type f 2>/dev/null

Ошибки парсинга сцены / поврежденный .tscn

Если Godot отказывается загружать сцену, отредактированную MCP, проверьте, что строки instance= не взяты в кавычки:

# Correct
instance=ExtResource("1_abc")

# Wrong (Godot rejects this)
instance="ExtResource(\"1_abc\")"

Запустите проект в headless-режиме, чтобы увидеть точную ошибку:

/path/to/Godot --path /path/to/project --headless --quit 2>&1

MCP отключается во время сессии

Это известная проблема некоторых реализаций хостов MCP. Решение: закройте и снова откройте ваш ИИ-клиент. Сам MCP-сервер не хранит состояние — повторное подключение безопасно.

Примеры рабочих процессов

2D шутер с видом сверху

"Create a 2D scene called Main.tscn"
"Add a CharacterBody2D called Player at the center"
"Create a movement + shooting script for the Player"
"Add an Area2D called Enemy that moves toward the player"
"Run the project and show errors"

3D платформер

"Create a 3D scene with a StaticBody3D floor (MeshInstance3D box, scale 20x1x20)"
"Add a CharacterBody3D player with a CapsuleShape3D collision"
"Create a 3D character controller script with jump and gravity"
"Add a Camera3D as a child of the player with offset Vector3(0, 2, 5)"

Режим только для чтения (Read-Only Mode)

READ_ONLY_MODE=true npx godot-mcp-pilot

Отключает все инструменты записи. Полезно для CI/CD или рабочих процессов проверки.

Разработка

git clone https://github.com/pushks18/godot-mcp-pilot
cd godot-mcp-pilot
npm install
npm run build

# Run the setup wizard
npm run setup

# Development mode (ts-node, no build step)
npm run dev

Структура проекта

godot-mcp-pilot/
├── src/
│   ├── index.ts               # Entry point
│   ├── server.ts              # MCP server + tool routing
│   ├── config.ts              # Godot path detection, env config
│   ├── godot-process.ts       # Process management (spawn, capture)
│   ├── tools/
│   │   ├── system.ts          # Version, project listing/info
│   │   ├── execution.ts       # Launch editor, run/stop project
│   │   ├── scene.ts           # Scene CRUD + node manipulation
│   │   ├── script.ts          # GDScript read/write/analyze
│   │   ├── assets.ts          # Asset listing/inspection
│   │   ├── project_settings.ts # Settings, autoloads, input maps
│   │   └── uid.ts             # Godot 4 UID management
│   └── utils/
│       ├── path.ts            # Path validation (prevents traversal)
│       ├── tscn.ts            # .tscn parser and serializer
│       └── project_godot.ts   # project.godot reader
└── scripts/
    ├── setup.js               # Interactive setup wizard
    └── godot_operations.gd    # Bundled GDScript for runtime ops

Совместимость

• Godot 4.x (основная цель — протестировано на 4.2, 4.3, 4.4)

• Godot 3.x — базовые инструменты работают; применяются различия в формате сцен

• Протокол MCP — спецификация от 2024-11-05

• Node.js — 18+

Безопасность

• Все пути к файлам проверяются на нахождение внутри директории проекта (защита от обхода пути)

• launch_editor и run_project запускают процессы только с безопасными, предопределенными аргументами

• Используйте READ_ONLY_MODE=true в ненадежных средах

• Сервер никогда не выполняет произвольные команды оболочки — только бинарный файл Godot

Лицензия

MIT