Godot MCP Server

Всеобъемлющий сервер FastMCP для разработки игр на Godot 4.x. Предоставляет инструменты для ИИ-ассистируемых рабочих процессов: управление проектами, файловые операции, поиск ассетов, разработка на GDScript и опциональный запуск Godot.

Вклад · Безопасность

Модель безопасности: Все проекты Godot, запись файлов и загрузки из Asset Library ограничены одной рабочей директорией на вашей машине (по умолчанию ~/godot-games). Сервер отклоняет пути за пределами этого дерева. См. Настройка рабочей области.

Выполнение кода: godot_run_game и godot_execute_script требуют GODOT_MCP_ALLOW_GODOT_EXEC в окружении сервера. Поставляемые JSON-конфиги MCP устанавливают его в 1, поэтому эти инструменты работают после копирования. Запуск python godot_mcp_server.py без этой переменной окружения оставляет выполнение выключенным, пока вы не экспортируете её. Чтобы ограничить установку в IDE, удалите переменную или установите её в 0. См. Выполнение Godot (окружение).

HTTP-транспорт: Привязка к 0.0.0.0 или :: открывает доступ к MCP-серверу на всех сетевых интерфейсах; предпочитайте 127.0.0.1, если вы не используете межсетевой экран или VPN.

Символические ссылки: GODOT_MCP_ROOT разрешается с переходом по симлинкам; указывайте на реальную директорию, которой управляете.

Возможности

Управление проектами

• Автоматическое обнаружение проектов Godot (project.godot); вывод списка всех проектов в рабочей области (godot_list_projects)

• Создание новых проектов в рабочей области (godot_create_project)

• Разбор настроек и конфигурации проекта; список автозагрузок и состояния плагинов редактора (для плагинов — только чтение)

• Обновление кэша проектов после изменений

Файловые операции

• Чтение/запись сцен (.tscn), скриптов (.gd), ресурсов (.tres)

• Создание новых скриптов, сцен, ресурсов из шаблонов

• Редактирование существующих файлов с заменой содержимого

• Проверка синтаксиса сцен и скриптов

Генерация кода

• Контроллеры движения CharacterBody2D/3D

• Паттерны конечных автоматов

• Пользовательские ресурсы

• Скрипты узлов с сигналами/экспортами

Управление ассетами

• Поиск ассетов по расширению, шаблону, glob

• Поиск неиспользуемых ассетов

• Поиск по содержимому файлов с помощью regex

• Поиск и загрузка из Godot Asset Library

• Просмотр репозиториев Godot на GitHub

Интеграция времени выполнения

• Поиск исполняемого файла Godot

• Проверка версии Godot

• Запуск игры в headless-режиме

• Выполнение кода GDScript

• Чтение журналов Godot

• Конфигурация отслеживания файлов

Related MCP server: Godot MCP

Установка

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

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

Консольная точка входа (после pip install -e .): godot-mcp-server (то же, что python godot_mcp_server.py).

Настройка рабочей области (обязательно)

MCP-сервер работает только с проектами Godot, находящимися в одной корневой папке. Это не позволяет ассистентам читать или записывать произвольные пути в вашей системе.

1. Создайте папку по умолчанию (один раз на машину):

   mkdir -p ~/godot-games

2. Поместите туда все игры Godot — каждая игра это отдельная подпапка, содержащая project.godot, например:

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

3. Откройте рабочую область IDE внутри ~/godot-games/.../your-game (или родительскую папку в ~/godot-games), чтобы процесс MCP мог обнаружить project.godot из текущей рабочей директории.

4. Своё расположение: Укажите абсолютный путь перед запуском сервера:

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

   В конфигурациях Cursor / Claude / других MCP добавьте env:

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

   Если не задано, по умолчанию используется $HOME/godot-games. Сервер создаёт эту директорию при запуске, если её нет.

5. Проверка во время работы: вызовите инструмент godot_get_workspace или прочитайте ресурс project://workspace, чтобы увидеть активный путь рабочей области.

Если инструменты сообщают, что проект не найден, вероятно, ваша текущая рабочая директория находится вне рабочей области, или project_path указывает за пределы GODOT_MCP_ROOT.

Выполнение Godot (окружение)

Запуск игры или выполнение GDScript выполняет код от имени вашего пользователя (так же, как запуск Godot из терминала). Сервер включает godot_run_game / godot_execute_script только тогда, когда GODOT_MCP_ALLOW_GODOT_EXEC установлен в принимаемое значение «включено».

Поставляемые конфиги (по умолчанию да): каждый пример JSON в этом репозитории (mcp_config.json, mcp_config.cursor.json и т.д.) включает:

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

Поэтому, если вы скопируете один из них в свою IDE, выполнение будет разрешено без дополнительных действий. Объединяйте другие ключи (например, GODOT_MCP_ROOT) в тот же объект env.

CLI без MCP-конфига: запуск python godot_mcp_server.py не устанавливает эту переменную; инструменты выполнения остаются заблокированными, пока вы не выполните export GODOT_MCP_ALLOW_GODOT_EXEC=1 (или не используете обёрточный скрипт).

Более строгие настройки: удалите GODOT_MCP_ALLOW_GODOT_EXEC из env или установите его в 0 / false / no / off, затем перезапустите MCP-клиент.

Принимаемые значения «включено»: 1, true, yes, on (без учёта регистра). Вызовите godot_get_workspace и проверьте godot_exec_allowed, чтобы убедиться.

Использование

CLI (stdio — для Claude Code/Cursor)

python godot_mcp_server.py

HTTP-сервер

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

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

Установите GODOT_MCP_ROOT в env MCP-сервера, если вы не используете стандартный ~/godot-games. См. Настройка рабочей области. Приведённые ниже примеры включают GODOT_MCP_ALLOW_GODOT_EXEC; см. Выполнение Godot (окружение).

Путь к серверу: В примерах используется "args": ["godot_mcp_server.py"] в предположении, что процесс MCP запускается с рабочей директорией в папке, содержащей скрипт (например, вы клонировали этот репозиторий). Если сервер не запускается, замените это на абсолютный путь к godot_mcp_server.py на вашей машине.

Установка в вашем редакторе

Разверните раздел и вставьте JSON в файл, который ожидает ваш инструмент. Тот же блок сервера godot находится в репозитории как mcp_config.*.json для копирования.

macOS / Linux (конфиг проекта или пользователя) — Настройки → MCP → Добавить новый глобальный MCP-сервер или создайте .cursor/mcp.json в корне проекта:

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

Windows — если python отсутствует в PATH для хоста MCP, используйте лаунчер или полный путь к python.exe, и предпочтительно абсолютный путь в 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"
      }
    }
  }
}

Объедините GODOT_MCP_ROOT с env, если вы не используете ~/godot-games (см. Настройка рабочей области).

Используйте настройки MCP / агента, которые предоставляет ваша сборка VS Code (часто Настройки → MCP или .vscode/mcp.json в проекте, в зависимости от версии и расширений). Вставьте ту же структуру, что и для Cursor:

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

Используйте абсолютный путь в args, если папка рабочей области не является корнем репозитория.

Отредактируйте файл конфигурации приложения:

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

Перезапустите Claude Desktop после сохранения.

Добавьте в ~/.claude/settings.json (или используйте claude mcp add, если ваш CLI это поддерживает — проверьте 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: отредактируйте ~/.codeium/windsurf/mcp_config.json или используйте CMD+SHIFT+P → “Windsurf: Настроить MCP-серверы”.

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

Вставьте в настройки MCP в Roo (проектные или глобальные), та же структура JSON, что выше. Копия в репозитории: 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"
    }
  }
}

Минимальная stdio-конфигурация — то же, что mcp_config.json в этом репозитории:

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

Ограничения (DoS / злоупотребления)

• Поиск по regex (godot_search_content): Максимальная длина шаблона; максимальное количество совпадений; файлы размером более 2 MiB пропускаются. Вредоносный regex всё ещё может быть дорогим — сохраняйте шаблоны простыми.

• Загрузка ZIP-ассетов: Максимальный размер загрузки, размер отдельного файла в распакованном виде, общий распакованный размер и количество файлов проверяются до извлечения (см. константы в верхней части godot_mcp_server.py).

• Идентификаторы Asset Library: asset_id для godot_get_asset_info / godot_download_asset должен содержать только цифры.

HTTP-режим (удалённый)

Используйте loopback, если вы не понимаете, что делаете:

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

Привязка ко всем интерфейсам (--host 0.0.0.0) логирует предупреждение и открывает доступ к MCP в вашей локальной сети без аутентификации на этом сервере.

Затем используйте serverUrl вместо command:

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

Запускайте только один транспорт для одного проекта (stdio или HTTP), не оба одновременно, чтобы избежать конфликтующих MCP-сессий.

Справочник инструментов

В godot_mcp_server.py зарегистрировано 40 MCP-инструментов (ищите @mcp.tool). Кратко:

Плагины редактора: этот сервер не записывает [editor_plugins] в project.godot (это позволяет избежать конфликта с открытым редактором). Устанавливайте аддоны с помощью указанных выше инструментов; пользователь включает плагины в Project Settings → Plugins в Godot; для проверки используйте godot_list_editor_plugins.

Ресурсы

Примеры

Создать игрока-платформера

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

Поиск ассетов

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

# Unused assets
find_unused_files()

Поиск в Asset Library

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

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

Запуск игры без графического интерфейса

Требуется GODOT_MCP_ALLOW_GODOT_EXEC (входит в поставляемые JSON-конфигурации MCP).

run_game(headless=True, quit_after_seconds=30)

Требования

• Python 3.10+

• Зависимости: fastmcp, urllib3 (см. pyproject.toml)

Разработка

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

Непрерывная интеграция выполняется на Python 3.10–3.14 (см. .github/workflows/ci.yml). Dependabot открывает еженедельные PR для pip и GitHub Actions.

Опционально: pip install pre-commit && pre-commit install использует .pre-commit-config.yaml.

Публикация на GitHub

1. Создайте пустой репозиторий на GitHub (без README/лицензии, если они уже есть локально), например godot-mcp-server.

2. Добавьте удалённый репозиторий и отправьте изменения:

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

Или с помощью GitHub CLI: gh repo create godot-mcp-server --public --source=. --remote=origin --push

После первой отправки CI запускается при каждой отправке и каждом PR. Замените sterion66 в URL бейджей в README, если вы используете другую учётную запись или организацию.

Лицензия

MIT