UnrealMCP — нативный MCP для Unreal Engine 5.7

English | 简体中文

UnrealMCP — это автономный плагин кода редактора Unreal Engine 5.7. Он позволяет Codex и другим локальным MCP-клиентам просматривать открытый Unreal Editor и управлять им, предоставляя ровно один MCP-инструмент: unreal.

Поставляемый плагин не требует Node.js, npm, Python-пакета или отдельно установленного шлюзового сервиса. Он содержит оба компонента времени выполнения:

• Binaries/Win64/UnrealMCPGateway.exe — нативный C++ stdio MCP-сервер, запускаемый MCP-клиентом.

• Binaries/Win64/UnrealEditor-UnrealMCP.dll — модуль редактора, владеющий loopback-воркером и отправляющий работу Unreal в игровой поток.

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

• Один инструмент: обнаружение возможностей, проверки здоровья, выполнение и управление асинхронными задачами — всё через unreal.

• Автономность: распространяемый плагин включает нативный stdio-шлюз и воркер Unreal Editor.

• Удобство для агентов: упорядоченные пакеты Python/консольных команд предоставляют гибкий путь к отражаемым API UE и проектным системам, таким как UnLua.

• Безопасность игрового потока: операции с UObject и редактором отправляются в игровой поток Unreal.

• Упаковка для Fab: автоматизация релизов создаёт чистый ZIP с одним плагином без внешнего рантайма.

flowchart LR
    C["Codex / MCP client"] -->|"stdio JSON-RPC"| G["Native gateway EXE"]
    G -->|"127.0.0.1 HTTP + optional bearer token"| P["UnrealMCP Editor plugin"]
    P -->|"Game Thread"| U["UE Python / console / UObject APIs"]

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

Каталог возможностей охватывает каждую группу плагинов, включённую официальным агрегатом AllToolsets из UE 5.8, через механизмы Python/отражения и консоли UE 5.7. Подсистема, существующая только в UE 5.8, не может быть создана в стандартной UE 5.7; эквивалентные рабочие процессы работают, когда доступна требуемая подсистема 5.7 или опциональный плагин. См. описание возможностей.

Содержание

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

• Установка

• Подключение Codex

• Проверка первого подключения

• API одного инструмента

• Модель возможностей

• Сборка из исходников

• Тестирование

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

• Безопасность и эксплуатационные ограничения

• Карта репозитория

• Заметки о распространении

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

1. Распакуйте плагин так, чтобы дескриптор находился по пути <Project>/Plugins/UnrealMCP/UnrealMCP.uplugin без дополнительной вложенной директории.

2. Включите Minimal MCP for Unreal Editor и Python Editor Script Plugin, затем перезапустите Unreal Editor.

3. Сохраните приведённую ниже конфигурацию в пользовательском ~/.codex/config.toml или в .codex/config.toml внутри доверенного проекта. Замените команду на абсолютный путь к шлюзу.

4. Перезапустите Codex, убедитесь с помощью /mcp, что unreal подключён, и попросите агента вызвать действие health.

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

Положительный результат включает ok: true, фактическую версию движка, is_game_thread: true и python_loaded: true. Unreal Editor должен оставаться открытым с загруженным целевым проектом.

Установка

Установка в проект

Закройте Unreal Editor перед копированием или заменой бинарных файлов. Распакуйте или скопируйте упакованную директорию UnrealMCP в:

<Project>/Plugins/UnrealMCP

Дескриптор должен оказаться по пути:

<Project>/Plugins/UnrealMCP/UnrealMCP.uplugin

Откройте проект, включите Minimal MCP for Unreal Editor и Python Editor Script Plugin в Edit → Plugins и перезапустите редактор.

Установка в движок

Чтобы сделать плагин доступным для нескольких проектов, использующих одну и ту же сборку движка, установите его в:

C:/Program Files/Epic Games/UE_5.7/Engine/Plugins/Marketplace/UnrealMCP

Могут потребоваться права администратора. Установка в проект обычно проще с точки зрения версионирования вместе с проектом и имеет приоритет при разработке.

Подключение Codex

Codex desktop, Codex CLI и IDE-расширение используют общую конфигурацию MCP. Локальные stdio-серверы запускаются из настроенной команды command. Конфигурация может находиться глобально в ~/.codex/config.toml или в .codex/config.toml внутри доверенного проекта. См. официальную документацию Codex MCP.

Используйте прямые слэши в пути TOML для Windows:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

Вы также можете добавить сервер в Codex desktop в Settings → MCP servers → Add → STDIO. После сохранения конфигурации перезапустите Codex и используйте /mcp, чтобы подтвердить подключение сервера.

MCP-клиент запускает только нативный шлюз. Он не запускает Unreal Editor. Откройте целевой проект в Unreal Editor перед вызовом инструмента.

Порт и аутентификация

Воркер привязывается только к 127.0.0.1. Следующие переменные окружения читаются редактором и шлюзом независимо:

Для аутентификации задайте одинаковый токен до запуска Unreal Editor и Codex. Не сохраняйте токен в системе контроля версий:

$env:UE_MCP_WORKER_TOKEN = '<a-long-random-token>'
$env:UE_MCP_WORKER_PORT = '18777'
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' 'C:\path\Project.uproject'

Если Codex запускается не из этой оболочки, укажите те же значения в конфигурации его MCP-сервера:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

[mcp_servers.unreal.env]
UE_MCP_WORKER_PORT = "18777"
UE_MCP_WORKER_TOKEN = "replace-with-the-same-token-used-by-the-editor"
UE_MCP_TIMEOUT_MS = "30000"

Проверка первого подключения

Попросите MCP-клиент вызвать unreal с:

{
  "action": "health"
}

Положительный ответ выглядит так:

{
  "ok": true,
  "data": {
    "ok": true,
    "engine_version": "5.7.x-...",
    "is_game_thread": true,
    "python_loaded": true,
    "transport": "loopback-http"
  }
}

Затем проверьте чтение данных движка:

{
  "action": "execute",
  "transaction": false,
  "commands": [
    {
      "kind": "python",
      "mode": "eval",
      "label": "engine-version",
      "code": "unreal.SystemLibrary.get_engine_version()"
    }
  ]
}

eval вычисляет одно Python-выражение и возвращает его значение. exec выполняет операторы или многострочный скрипт. Модуль unreal доступен в среде выполнения Python плагина.

API одного инструмента

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

Обнаружение возможностей

Изучите независимый каталог возможностей перед выбором API UE:

{
  "action": "discover",
  "query": "create and compile a blueprint",
  "limit": 5
}

Используйте domain для точного домена, например blueprint, asset, niagara, pcg, slate, umg или unlua. Вызов discover без запроса возвращает записи каталога вплоть до запрошенного лимита.

Выполнение упорядоченного пакета

Пакет execute принимает до 100 команд Python или консольных команд. Команды выполняются по порядку в игровом потоке.

{
  "action": "execute",
  "run": "sync",
  "transaction": true,
  "continue_on_error": false,
  "timeout_ms": 120000,
  "commands": [
    {
      "kind": "python",
      "mode": "exec",
      "label": "select-all-static-mesh-actors",
      "code": "subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\nactors = subsystem.get_all_level_actors()\nsubsystem.set_selected_level_actors([a for a in actors if isinstance(a, unreal.StaticMeshActor)])"
    },
    {
      "kind": "console",
      "label": "show-fps",
      "command": "stat fps"
    }
  ]
}

• transaction по умолчанию равен true и создаёт одну запись undo редактора, если весь пакет выполняется успешно.

• continue_on_error по умолчанию равен false; если включён, последующие команды всё равно выполняются, но общий результат остаётся неуспешным при сбое любой команды.

• timeout_ms принимает значения от 100 до 3600000 миллисекунд и переопределяет UE_MCP_TIMEOUT_MS для этого вызова.

• Результаты Python и перехваченные журналы Python или вывод консоли возвращаются для каждой команды.

Используйте transaction: false для запросов только на чтение и API, которые не участвуют в транзакциях Unreal. Транзакция Unreal — это запись undo, а не откат файловой системы или системы контроля версий.

Запуск и проверка асинхронных задач

Для длинного пакета отправьте его асинхронно:

{
  "action": "execute",
  "run": "async",
  "timeout_ms": 3600000,
  "commands": [
    {
      "kind": "console",
      "command": "Automation RunTests Project"
    }
  ]
}

Ответ содержит task_id. Опрашивайте задачи или получайте их список с помощью:

{ "action": "task", "command": "get", "task_id": "<uuid>" }

{ "action": "task", "command": "list" }

Отметьте задачу как отменённую с помощью:

{ "action": "task", "command": "cancel", "task_id": "<uuid>" }

Состояние задачи хранится в процессе шлюза и теряется, когда Codex останавливает этот процесс. Отмена выполняется по мере возможности: она помечает отслеживание как отменённое, но работа, уже отправленная в игровой поток Unreal, может всё же завершиться и не откатывается.

Модель возможностей

Плагин намеренно избегает сотен узких инструментов-обёрток. discover предоставляет рецепты и предпочтительные API; execute обращается к отражаемой Python-поверхности UE 5.7, консольным командам, опциональным плагинам движка и проектным API, таким как UnLua.

Каталог охватывает все 21 группу AllToolsets из UE 5.8, включая работу с редактором/ассетами/Blueprint, ИИ и навигацию, анимацию, автоматизацию, конфигурацию, диалоги, Data Registry, Dataflow, Game Features, Gameplay Tags и GAS, Niagara, PCG, физику, плагины, семантический поиск, Slate, StateTree, UMG и World Conditions.

Покрытие — это покрытие маршрутизации и механизмов, а не утверждение, что классы, существующие только в UE 5.8, есть в UE 5.7. Дополнительные рабочие процессы требуют включения соответствующего плагина движка или проекта. Обоснование и пять этапов минимизации описаны в минимизации инструментов.

Сборка из исходников

Требования:

• Установка исходников/сборки Unreal Engine 5.7. Скрипты по умолчанию используют C:\Program Files\Epic Games\UE_5.7.

• Инструментарий Visual Studio C++, поддерживаемый UE 5.7.

• PowerShell.

• Node.js 20+ только для опциональных тестов протокола MCP; Node не является зависимостью времени выполнения продукта.

Скомпилируйте нативный шлюз на месте:

.\scripts\build-native-gateway.ps1

Соберите полный пакет плагина в новую директорию:

.\scripts\build-plugin.ps1 -OutputDirectory 'C:\Temp\UnrealMCP-Package'

Создайте Fab ZIP с одной верхнеуровневой директорией:

.\scripts\build-fab-package.ps1 -OutputFile '.\artifacts\UnrealMCP-0.2.0-UE5.7-Win64.zip'

Упакованный плагин содержит дескриптор, исходный код, конфигурацию, ресурсы, нативные DLL и EXE, уведомления о лицензиях, README на английском и упрощённом китайском, а также проектную документацию. Fab ZIP содержит ровно одну верхнеуровневую директорию UnrealMCP/ и исключает Intermediate, PDB-файлы, Node-пакеты и тестовый проект для разработки.

Каждая версия движка и платформа требует собственного скомпилированного и протестированного бинарного пакета. Текущий дескриптор ориентирован только на Win64.

Тестирование

Запустите проверки метаданных и нативные интеграционные тесты MCP (современные/устаревшие):

npm install
npm test

Запустите полный путь: нативный stdio-шлюз → loopback-воркер → игровой поток → UE Python:

.\scripts\build-native-gateway.ps1
.\scripts\test-worker-e2e.ps1

Сквозной тест запускает включённый UE57MCPTest.uproject без графического интерфейса на изолированном порту и завершает его после проверки. Закройте посторонние экземпляры автоматических тестов, если выбранный порт занят.

Шлюз записывает сообщения протокола MCP только в stdout, а диагностику — в stderr. Ошибки запуска плагина, привязки, авторизации и выполнения отображаются в журнале вывода Unreal в разделе LogUnrealMCP.

Безопасность и эксплуатационные ограничения

execute намеренно разрешает произвольные Python-команды Unreal и команды консоли. Относитесь к доступу к этому инструменту как к разрешению агенту управлять открытым проектом редактора.

• Воркер привязывается только к loopback; это не удалённый сетевой сервис.

• Bearer-аутентификация необязательна, но рекомендуется на общих машинах.

• Размер тела запроса ограничен 4 МиБ, пакет — 100 командами.

• Доступ к UObject и редактору выполняется в игровом потоке (Game Thread).

• Не размещайте секреты в аргументах инструмента, файлах проекта, журналах или конфигурации Codex в системе контроля версий.

• Используйте систему контроля версий для разрушительных операций с ассетами, конфигурацией, плагинами и файловой системой.

Карта репозитория

Примечания о распространении

Сгенерированный ZIP-файл имеет структуру единого устанавливаемого плагина UE Code Plugin, подходящего для технической проверки Fab. Публикация в маркетплейсе по-прежнему требует метаданных продавца/объявления и визуальных материалов, таких как значок и скриншоты плагина, а также пакета, протестированного для каждой заявленной версии движка и платформы.

Сведения о лицензии приведены в LICENSE, а уведомления о сторонних компонентах — в THIRD_PARTY_NOTICES.md. Дополнительные заметки по проектированию: архитектура, покрытие возможностей и минимизация инструментов.

Если этот проект помог вам, пожалуйста, подумайте о том, чтобы поставить ему звезду ⭐