Unity MCP Server

Сервер MCP для Unity Editor. Позволяет ИИ-агентам, таким как Claude Code, просматривать, изменять, тестировать и делать снимки экрана вашего проекта.

Ключевые особенности

• 73 инструмента: сцены, игровые объекты, компоненты, префабы, трансформы, тесты, рефлексия + декомпиляция, C# eval, захват интерфейса

• Клиенты с нулевой конфигурацией: один клик (или одна команда) на машину, после чего каждый проект и редактор подключаются автоматически. Никаких портов, токенов или настройки для каждого проекта

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

• MCP-ресурсы: логи консоли, иерархия сцены, результаты тестов, файлы проекта

• Unity 2022.3+ (рекомендуется Unity 6), Node.js 18+

Related MCP server: Unity MCP Server

Установка

Package Manager > + > «Добавить пакет из git URL»:

https://github.com/Singtaa/UnityMCP.git

Или склонируйте / добавьте как submodule в Packages/com.singtaa.unity-mcp.

Настройка (один раз на машину)

1. Откройте проект в Unity. Сервер запускается автоматически, лаунчер разворачивается в ~/.unity-mcp/stdio.js

2. Window > Unity MCP Server > Set up Claude Code

Готово. Аналог в терминале:

# macOS / Linux
claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

# Windows
claude mcp add --scope user --transport stdio unity -- node "%USERPROFILE%\.unity-mcp\stdio.js"

Теперь каждая сессия Claude Code в любом проекте Unity подключается к редактору именно этого проекта. Несколько редакторов рядом: каждая сессия находит свой. Если редактор закрыт или перезагружается: инструменты возвращают понятную ошибку и восстанавливаются сами. Открытие редактора прямо во время сессии тоже работает: сессия, запущенная при закрытом редакторе, немедленно регистрирует список инструментов (обслуживается из кэша для каждого проекта) и синхронизируется вживую, как только редактор поднимается — без перезапуска клиента.

Под капотом: редактор записывает per-session маяк (Temp/UnityMcp_Endpoint.json, удаляется при выходе, никогда не устаревает). Лаунчер определяет проект сессии (CLAUDE_PROJECT_DIR, иначе поиск вверх от cwd, UNITY_MCP_PROJECT) переопределяет оба) и проксирует MCP на живой endpoint этого проекта, перечитывает маяк при каждом запросе. Он объявляет tools.listChanged и следит за маячком: когда появляется редактор (или другой редактор берёт проект на себя), он отправляет уведомления list_changed, чтобы клиенты догрузили списки инструментов и ресурсов с середине сессии. Развертывание лаунчера в ~/.unity-mcp/stdio.js обновляется только через LAUNCHER_VERSION, поэтому редакторы с разными версиями пакета никогда не конкурируют за файл.

Другие MCP-клиенты: тот же лаунчер или простой HTTP (endpoint и токен отображаются в окне).

Инструменты

Примечательно:

• unity_eval: компилирует и выполняет C#-фрагмент в редакторе без перезагрузки домена. Форма выражения возвращает его значение, форма оператора использует return. Стандартные объекты using импортируются, ведущие строки using поднимаются наверх. Встроенный Roslyn (потолок C# 9). Первый вызов прогревается несколько секунд, затем десятки миллисекунд на компиляцию

• unity_capture_panel: рендерит PanelSettings UI Toolkit в PNG за кадром, без оформления сцены, работает в режиме редактирования и в режиме игры. Автоматически определяет активный UIDocument

• unity_assets_find: синтаксис запросов окна Project (t:Material, t:Prefab ui, l:MyLabel), функция ограничения папкой, ограниченный результат с общим количеством

• unity_reflection_decompile: полный C#-исходный код любого загруженного типа или метода

• Особенности: подождите ~1 с после перезагрузки домена перед тестовыми инструментами; unity_capture_game_view работает только в режиме игры на Unity 6.3+

Ресурсы

unity://console/logs · unity://hierarchy · unity://hierarchy/{scene} · unity://tests/results · unity://project/files

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

ProjectSettings/McpSettings.json (его нужно коммитить): HTTP-порт 5173, IPC-порт 52100, автозапуск, токен авторизации.

Порты заняты сервером другого проекта? Свободная пара выделяется автоматически и хранится на машине в UserSettings/McpPortOverride.json (исключено через gitignore), поэтому перестановки портов никогда не уходят в команду. Личность проекта подтверждается при каждом подключении моста: редактор никогда не может присоединиться к серверу другого проекта, даже при неправильной настройке портов.

Ручной запуск сервера: node src/server.js при условии, что MCP_PROJECT_ROOT содержит путь к проекту.

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

Дополняет, а не конкурирует:

• Unity CLI управляет жизненным циклом редактора: установка, unity open, сборки, CI

• UnityMCP управляет живой сессией редактора: захват интерфейса, декомпиляция, eval, циклы тестирования, маршрутизация без настройки

• Типичный цикл агента: unity open <project> через CLI, редактор запускается, поднимаются сервер и маяк, лаунчер подключается. Никакой настройки с любой стороны

• Редакторы, запущенные через CLI, работают в фоне без фокуса. UnityMCP построен и протестирован именно для этого (безопасный запуск в фоне, повторы и стабильность при перезагрузках домена)

• Портов и имён инструментов не пересекаются. Регистрируйте оба

Архитектура

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├──────────────────────────────┬──────────────────────────────┤
│  stdio launcher              │  (or direct HTTP clients)    │
│  ~/.unity-mcp/stdio.js       │                              │
│  resolves the session's      │                              │
│  project, reads its beacon   │                              │
│  Temp/UnityMcp_Endpoint.json │                              │
├──────────────────────────────┴──────────────────────────────┤
│           HTTP JSON-RPC (Port 5173, per project)            │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

Каждый открытый проект запускает собственный Node-сервер. Лаунчер — это общая пакетная точка входа, которая направляет каждую сессию к нужному серверу.

Разработка

• Unity-тесты: Window > General > Test Runner (EditMode + PlayMode)

• Тесты лаунчера: npm test в Server~/

• История изменений: CHANGELOG.md

Лицензия

MIT. См. LICENSE.