Godot MCP Server

godot-mcp позволяет MCP-клиентам проверять, валидировать, тестировать, экспортировать и запрашивать проекты Godot. Он поддерживает headless-команды Godot и, опционально, live-состояние из открытого редактора Godot.

Требования

• Node.js 18 или новее

• Godot 4.1 или новее, установленный локально

• Проект Godot, содержащий project.godot

Инструменты live-редактора дополнительно требуют аддон MCP Bridge, описанный ниже. Остальные инструменты работают в headless-режиме.

Related MCP server: godot-ai-mcp

Установка

Из локального репозитория

npm install
npm run build

Из npm (после публикации)

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

Настройка MCP-клиента

Всегда указывайте путь к проекту. MCP-клиенты для настольных систем обычно запускают серверы в своей собственной рабочей директории, поэтому автоматическое обнаружение проекта само по себе ненадёжно.

{
  "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"
      }
    }
  }
}

Эквивалентные параметры командной строки:

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

GODOT_PATH/--godot является опциональным только в том случае, если исполняемый файл godot уже находится в PATH. В Windows предпочтителен исполняемый файл _console.exe.

Включение инструментов live-редактора

1. Скопируйте godot-plugin/addons/mcp_bridge в <ваш-проект>/addons/mcp_bridge.

2. В Godot откройте Project > Project Settings > Plugins и включите MCP Bridge.

3. Держите редактор Godot открытым при использовании live-инструментов.

Мост по умолчанию прослушивает 127.0.0.1:7000. Установите mcp/plugin/port в project.godot, чтобы переопределить его; сервер считывает этот параметр из проекта, настроенного выше. Исключите addons/mcp_bridge/* из пресетов экспорта для продакшена.

Инструменты

• Проект и экспорт: get_project_settings, list_export_presets, export_project

• Тесты и валидация: run_tests, validate_scene, validate_script, run_scene, format_gdscript

• Сцены и ресурсы: inspect_scene_tree, find_nodes, get_node_properties, get_node_connections, list_resources, get_resource_dependencies, resolve_path, get_resource_info

• Документация: verify_api, get_help

• Live-редактор: get_editor_selection, get_open_scenes

Большинство инструментов возвращают структурированный JSON-результат с success, data, errors, warnings и метаданными о времени выполнения.

Разработка и проверка

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 запускает как Node/MCP-тесты, так и проверки аддона Godot при пушах и pull request'ах.

Чек-лист релиза

1. Обновите версию в package.json.

2. Запустите npm test, npm run test:godot и npm pack --dry-run.

3. Опубликуйте с помощью npm publish и создайте соответствующий релиз на GitHub.

Лицензия

Этот проект лицензирован в соответствии с MIT License.