MCP 서버로 Unity·Unreal 에디터 자동화 툴 개발하는 방법

TL;DR

MCP(Model Context Protocol)는 AI 클라이언트가 정해진 도구 목록을 발견하고 안전한 입력 형식으로 호출하게 하는 프로토콜이다. Unity와 Unreal 에디터 기능을 MCP 도구로 얇게 감싸면 자연어 요청을 에셋·씬·빌드 파이프라인의 검증 가능한 자동화 작업으로 바꿀 수 있다. 핵심은 엔진 API를 AI에 직접 노출하지 않고 권한이 제한된 명령과 명확한 결과 모델을 제공하는 데 있다.

MCP 서버와 게임 에디터 자동화는 왜 잘 맞을까?

게임 에디터 자동화에는 반복적이지만 규칙이 많은 작업이 많다. 예를 들어 선택한 프리팹의 누락 컴포넌트를 찾거나 주소 지정 가능 에셋 설정을 검사하고 레벨 안의 라이트 수를 집계하는 작업이다. 이러한 작업은 사람이 매번 메뉴를 열어 확인하기보다 입력과 결과가 정형화된 도구 호출로 만들기 좋다.

MCP 서버는 AI 클라이언트에 tools/list로 사용 가능한 도구를 알리고 클라이언트가 tools/call로 도구를 실행하는 구조를 제공한다. Unity 또는 Unreal은 실제 엔진 API를 실행하고 MCP 서버는 요청 검증·권한 통제·결과 직렬화를 맡는다.

구성 요소	책임	예시
AI 클라이언트	사용자 의도 해석, 도구 선택	“현재 씬의 누락 참조를 검사해 줘”
MCP 서버	스키마 검증, 접근 제어, 호출 중계	`scan_missing_references` 호출
Unity/Unreal 브리지	에디터 스레드에서 엔진 API 실행	`AssetDatabase`, `EditorLevelLibrary`
도구 구현	좁고 재현 가능한 작업 수행	프리팹 검사, 머티리얼 생성, 빌드 리포트 수집

MCP 서버와 Unity 및 Unreal 에디터 자동화 요청 흐름

Unity·Unreal 연동 구조는 어떻게 설계할까?

에디터 API는 대체로 메인 스레드 제약이 있다. 반면 MCP 서버의 JSON-RPC 요청 처리기는 비동기 네트워크 스레드에서 동작할 수 있다. 따라서 서버가 엔진 API를 직접 호출하는 구조보다 요청을 에디터 내부의 작업 큐로 전달하고 메인 스레드에서 처리하는 구조가 안전하다.

flowchart LR
    A[AI 클라이언트] -->|tools/call JSON-RPC| B[MCP 서버]
    B -->|검증된 명령| C[에디터 브리지]
    C -->|메인 스레드 작업 큐| D[Unity 또는 Unreal 에디터]
    D -->|구조화된 실행 결과| C
    C --> B
    B -->|text 또는 JSON 결과| A

권장하는 도구 경계

도구 하나는 사용자가 이해할 수 있는 단일 작업이어야 한다. run_editor_command처럼 임의 코드를 실행하는 도구는 편해 보이지만 권한 관리와 재현성이 나빠진다. 대신 아래처럼 의도를 드러내는 명령으로 나눈다.

도구 이름	입력	결과	변경 여부
`find_missing_references`	`scenePath`	누락된 오브젝트 목록	읽기
`create_material`	`path`, `shaderName`, `color`	생성된 에셋 경로	쓰기
`validate_prefab`	`prefabPath`, `rules`	규칙별 통과·실패	읽기
`build_player`	`target`, `outputPath`	빌드 리포트와 오류	쓰기

쓰기 작업은 dryRun과 confirm 입력을 함께 두는 편이 좋다. dryRun: true에서는 변경 예정 항목만 반환하고 실제 변경은 명시적인 확인 뒤에 실행한다.

Unity 에디터 자동화 도구를 C#으로 구현하는 방법

Unity에서는 EditorApplication.delayCall 또는 자체 작업 큐를 사용해 에디터 메인 스레드에서 작업을 수행할 수 있다. 아래 예제는 프리팹 경로를 받아 누락된 MonoBehaviour 스크립트를 검사하는 에디터 서비스의 핵심 형태다.

using System;
using System.Collections.Generic;
using UnityEditor;
using UnityEngine;

public static class PrefabValidationService
{
    public static ValidationResult FindMissingScripts(string prefabPath)
    {
        var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(prefabPath);
        if (prefab == null)
        {
            return ValidationResult.Failure($"Prefab not found: {prefabPath}");
        }

        var missingObjectPaths = new List<string>();
        foreach (var transform in prefab.GetComponentsInChildren<Transform>(true))
        {
            var components = transform.GetComponents<Component>();
            foreach (var component in components)
            {
                if (component == null)
                {
                    missingObjectPaths.Add(GetHierarchyPath(transform));
                    break;
                }
            }
        }

        return ValidationResult.Success(missingObjectPaths);
    }

    private static string GetHierarchyPath(Transform current)
    {
        return current.parent == null
            ? current.name
            : $"{GetHierarchyPath(current.parent)}/{current.name}";
    }
}

public record ValidationResult(bool Ok, string Error, List<string> MissingObjects)
{
    public static ValidationResult Success(List<string> objects) => new(true, null, objects);
    public static ValidationResult Failure(string error) => new(false, error, new());
}

MCP 도구 정의에서는 입력을 JSON Schema로 제한한다. prefabPath를 프로젝트의 Assets/ 하위 경로로만 허용하면 디스크 전체에 대한 접근을 막을 수 있다.

{
  "name": "validate_prefab_missing_scripts",
  "description": "프리팹 안의 누락된 MonoBehaviour 스크립트를 찾습니다.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prefabPath": {
        "type": "string",
        "pattern": "^Assets/.+\\.prefab$"
      }
    },
    "required": ["prefabPath"],
    "additionalProperties": false
  }
}

Unity 도구 호출 결과는 왜 구조화해야 할까?

사람에게는 문장 하나로 충분해도 AI 클라이언트와 후속 자동화에는 구조화된 결과가 유리하다. 성공 여부, 변경된 파일, 경고, 다음 조치를 분리하면 AI가 결과를 근거로 다음 도구를 선택할 수 있다.

{
  "ok": true,
  "summary": "누락된 스크립트 2개를 찾았습니다.",
  "items": [
    {"path": "Player/Weapon", "issue": "Missing MonoBehaviour"},
    {"path": "UI/HUD", "issue": "Missing MonoBehaviour"}
  ],
  "changedFiles": [],
  "warnings": []
}

Unreal Engine 에디터 자동화는 어떤 방식으로 연결할까?

Unreal Engine에서는 Editor Utility, Python API, C++ Editor Module 또는 Remote Control API를 브리지로 선택할 수 있다. 기존 파이프라인이 블루프린트 중심이라면 Editor Utility Widget을 호출하는 방식이 적합하고 대규모 에셋 검증처럼 성능과 타입 안정성이 중요하다면 C++ Editor Module이 유리하다.

방식	적합한 작업	장점	주의점
Python API	일괄 에셋 수정, 빠른 프로토타입	작성 속도	배포와 실행 권한 관리
Editor Utility	아티스트용 도구, 블루프린트 연계	에디터 UI 통합	서버 호출 경계 별도 설계 필요
C++ Editor Module	검증, 대규모 처리, 플러그인	성능, 타입 안정성	컴파일·모듈 의존성 관리
Remote Control API	노출된 프로퍼티 제어	외부 연동 간단	임의 기능 노출을 피해야 함

예를 들어 EditorAssetLibrary.list_assets()로 특정 경로의 에셋을 수집하고 네이밍 규칙 검사 결과만 MCP 응답으로 반환할 수 있다. 중요한 점은 AI가 Unreal Python 문자열을 직접 실행하게 하지 않는 것이다. 허용된 검사 함수와 허용된 콘텐츠 경로만 노출해야 한다.

MCP 기반 에디터 자동화 구현 절차

1. 반복 작업을 읽기·쓰기·위험 작업으로 분류한다

먼저 자동화 후보를 나열하고 영향도를 정한다. 씬 통계나 에셋 검사 같은 읽기 작업부터 시작하면 안전하게 가치와 호출 품질을 검증할 수 있다. 에셋 생성과 설정 변경은 쓰기 작업으로 분리하고 빌드·삭제·대량 이름 변경은 위험 작업으로 취급한다.

2. 입력 스키마와 결과 계약을 먼저 만든다

각 도구에 필수 입력, 경로 제한, 최대 처리 개수, 시간 제한을 정의한다. 결과에는 최소한 ok, summary, items, warnings, changedFiles를 포함한다. 대량 에셋 작업은 maxAssets를 두고 기본값을 작게 설정해 실수로 프로젝트 전체를 처리하지 않게 한다.

3. 에디터 메인 스레드 브리지를 구현한다

요청 수신과 엔진 API 호출을 분리한다. Unity는 EditorApplication.update에서 큐를 소비하고 Unreal은 게임 스레드 또는 에디터 태스크 그래프에서 실행하도록 구성한다. 작업별 타임아웃과 취소 토큰을 두면 클라이언트가 연결을 끊은 뒤에도 불필요한 작업이 계속되는 문제를 줄일 수 있다.

4. 드라이런과 변경 기록을 추가한다

쓰기 도구에는 dryRun을 기본값으로 둔다. 실제 실행 시에는 수정 전후 경로, 생성·변경된 에셋, 실패 원인을 로그와 응답에 남긴다. 버전 관리 환경에서는 변경 파일 목록을 반환해 사용자가 커밋 전 검토할 수 있게 한다.

성능과 안정성을 어떻게 검증할까?

에디터 자동화는 게임 런타임 프레임보다 에디터 응답성과 작업 재현성이 중요하다. 다음 지표를 도구별로 기록하면 병목을 빠르게 찾을 수 있다.

지표	의미	권장 대응
처리 에셋 수	요청 범위	페이지네이션, `maxAssets` 제한
실행 시간	에디터 정지 체감	배치 크기 축소, 진행 상황 반환
메모리 증가량	대규모 로드 영향	필요한 메타데이터만 읽기
변경 파일 수	작업 영향 범위	드라이런과 확인 단계 적용
실패율	스키마·환경 문제	오류 코드와 재시도 가능 여부 제공

에셋 검사 비용은 대략 처리 대상 수에 비례한다.

T(N) = T_{startup} + N \times T_{asset}

따라서 모든 요청에서 프로젝트 전체를 순회하기보다 경로, 에셋 유형, 최대 개수를 입력으로 받는 것이 중요하다. Unity에서는 AssetDatabase.FindAssets 결과를 제한하고 Unreal에서는 콘텐츠 브라우저 경로 단위로 범위를 좁힌다.

드라이런 결과를 검토한 뒤 Unity 또는 Unreal 에셋 변경을 승인하는 자동화 화면

자주 묻는 질문 (FAQ)

MCP 서버가 Unity 또는 Unreal 에디터 내부에서 반드시 실행되어야 하나요?

반드시 그렇지는 않다. 서버는 별도 프로세스로 실행할 수 있지만 엔진 API 호출은 에디터 프로세스와 통신하는 브리지가 처리해야 한다. 간단한 내부 도구는 에디터 플러그인에 서버를 포함하고 팀 공용 도구는 별도 서버와 로컬 브리지를 분리하는 방식이 관리하기 쉽다.

AI에게 C# 또는 Python 코드를 직접 실행하게 해도 되나요?

권장하지 않는다. 임의 코드 실행은 파일 삭제, 네트워크 접근, 예상하지 못한 프로젝트 변경으로 이어질 수 있다. 입력 스키마가 있는 전용 MCP 도구와 허용 경로 목록을 사용해야 한다.

처음 만들어 볼 MCP 도구는 무엇이 좋나요?

validate_prefab, find_missing_references, list_large_textures처럼 읽기 전용 검사 도구가 적합하다. 성공 기준이 명확하고 프로젝트를 변경하지 않으므로 팀이 결과 형식과 도구 호출 흐름에 익숙해지기 좋다.

마무리

MCP 기반 Unity·Unreal 에디터 자동화의 목적은 AI가 에디터를 무제한 조작하게 만드는 것이 아니다. 자주 쓰는 개발 작업을 작은 도구 계약으로 분해하고 메인 스레드 실행·스키마 검증·드라이런·변경 기록을 갖춘 안전한 인터페이스로 제공하는 것이다. 읽기 전용 검증 도구부터 시작해 신뢰할 수 있는 결과 모델을 만든 뒤 승인 절차가 있는 쓰기 작업으로 확장하는 순서가 가장 실용적이다.