GoPeak — MCP-сервер для Godot

GoPeak — это MCP-сервер, который позволяет AI-ассистентам управлять проектами Godot: запускать, редактировать сцены, скрипты, ресурсы, отлаживать и взаимодействовать с рантаймом. Работает из коробки с Claude Desktop, Cursor, Cline и другими клиентами, поддерживающими MCP.

Быстрый старт (3 минуты)

Требования

• Godot 4.x
• Node.js 18+
• MCP-совместимый клиент

1. Запуск GoPeak

npx -y gopeak

Или глобальная установка:

npm install -g gopeak
gopeak

2. Конфигурация MCP-клиента

Добавьте в настройки вашего MCP-клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gopeak"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

Режим compact включён по умолчанию: доступно 33 базовых инструмента и 22 динамические группы (всего 78 дополнительных), которые активируются по запросу — это экономит токены.

3. Примеры первых запросов

• «List Godot projects in /your/projects and show project info.»
• «Create scenes/Player.tscn with CharacterBody2D root and add a movement script.»
• «Run project, get debug output, then fix top error.»

Зачем GoPeak

• Реальный цикл обратной связи: запускайте игру, смотрите логи и тут же исправляйте.
• 110+ инструментов: от сцен и скриптов до LSP/DAP, ввода-вывода и ассетов.
• Экономия токенов: динамические группы активируются только тогда, когда они нужны.
• Глубокая интеграция с Godot: ClassDB, инспекция рантайма, точка останова, мост для редактирования сцен/ресурсов.
• Подходит для: соло-разработчиков, команд, отладки с брейкпоинтами и стектрейсами.

Модель инструментов (важно)

GoPeak поддерживает три профиля:

• compact (по умолчанию): 33 базовых инструмента + 22 группы (78 дополнительных).
• full: все 110+ инструментов.
• legacy: то же, что full.

Настраивается через переменную окружения GOPEAK_TOOL_PROFILE (или MCP_TOOL_PROFILE как fallback).

Динамические группы (режим compact)

Группы активируются автоматически при поиске через tool.catalog или вручную через tool.groups.

Пример автоматической активации:

«Use tool.catalog with query animation and show relevant tools.»

Пример ручной активации:

«Use tool.groups to activate the dap group for debugging.»

Сброс групп:

«Use tool.groups to reset all active groups.»

Когда группы активируются/деактивируются, сервер отправляет уведомление tools/list_changed, и клиент (Claude Code, Claude Desktop) автоматически обновляет список.

Список групп: scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.

Пагинация

Даже в профиле full инструменты передаются постранично (по умолчанию 33 на страницу) — клиент догружает следующую страницу только при необходимости. Размер страницы настраивается через GOPEAK_TOOLS_PAGE_SIZE.

Установка

A) Через npx (рекомендуется)

npx -y gopeak

B) Глобальная установка

npm install -g gopeak
gopeak

C) Из исходников

git clone https://github.com/HaD0Yun/godot-mcp.git
cd godot-mcp
npm install
npm run build
node build/index.js

Также доступен псевдоним команды: godot-mcp.

Установка аддона (рекомендуется)

Для полной функциональности (Auto Reload, Editor Bridge, Runtime Addon) выполните в корневой папке проекта Godot:

Linux / macOS:

curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash

Windows (PowerShell):

iwr https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex

После установки включите плагины в Project Settings → Plugins (особенно godot_mcp_editor).

Переменные окружения

Порты

Минимальные профили портов: для базового редактирования достаточно порта моста (6505); для рантайм-действий нужен ещё 7777; для полной отладки — 6005, 6006, 7777.

Основные возможности

• Управление проектом: запуск редактора, запуск/остановка игры, захват отладочного вывода.
• Редактирование сцен: создание, добавление/удаление/репарентинг узлов, изменение свойств.
• Скрипты: создание, изменение, инспекция структуры.
• Ресурсы: материалы, шейдеры, тайлсеты.
• Сигналы и анимация: подключение сигналов, создание анимаций и State Machine.
• Рантайм: инспекция живого дерева, установка свойств, вызов методов, метрики.
• LSP + DAP: диагностика, автодополнение, ховеры, брейкпоинты, пошаговое выполнение, стектрейсы.
• Ввод и скриншоты: эмуляция клавиатуры/мыши/экшенов, захват viewport.
• Библиотека ассетов: поиск и загрузка CC0-ассетов (Poly Haven, AmbientCG, Kenney).
• Project Visualizer: визуализация архитектуры проекта с помощью visualizer.map.

Примеры промптов

Сборка:

«Create a Player scene with CharacterBody2D, Sprite2D, CollisionShape2D, and a basic movement script.» «Add an enemy spawner scene and wire spawn signals to GameManager.»

Отладка:

«Run the project, collect errors, and fix the top 3 issues automatically.» «Set a breakpoint at scripts/player.gd:42, continue execution, and show stack trace when hit.»

Рантайм-тестирование:

«Press ui_accept, move mouse to (400, 300), click, then capture a screenshot.» «Inspect live scene tree and report nodes with missing scripts or invalid references.»

Решение проблем

• Godot not found → задайте явный путь в GODOT_PATH.
• Нет инструментов MCP → перезапустите MCP-клиент.
• Путь к проекту невалидный → убедитесь, что файл project.godot существует.
• Рантайм-инструменты не работают → установите и включите аддон runtime addon.
• Нужный инструмент не отображается → выполните tool.catalog для поиска и автоактивации группы, или используйте tool.groups вручную.

Документация и ссылки

• Architecture
• Platform Roadmap
• CHANGELOG
• ROADMAP
• CONTRIBUTING

Лицензия

MIT — подробнее в LICENSE.

Благодарности

• Оригинальный MCP-сервер: Coding-Solo/godot-mcp
• Улучшения GoPeak: HaD0Yun
• Project Visualizer вдохновлён: tomyud1/godot-mcp