Unity MCP 서버

MCP (Model Context Protocol)를 통해 Unity Editor 기능을 외부 AI 에이전트에 노출하는 Unity Editor 플러그인입니다.

에이전트(Kiro, Cursor, Claude Desktop 등)는 표준 MCP 프로토콜을 통해 Unity Editor에 연결하여 에디터 기능을 호출할 수 있습니다.

특징

Streamable HTTP 전송 — MCP 2025-03-26 사양 기반, 단일 HTTP 엔드포인트
프로세스 내 실행 — 외부 Node.js/Python 프로세스 없이 Editor 내에서 직접 시작
확장 가능한 도구 시스템 — IMcpTool 인터페이스를 구현하여 핵심 코드 수정 없이 새 도구 등록 가능
Domain Reload 자동 복구 — PlayMode 진입/종료 후 서비스 자동 재시작

내장 도구

도구	분류	기능
`console_getLogs`	debug	Unity Console의 최근 N개 로그 가져오기
`debug_getStackTrace`	debug	최근 Error/Exception의 전체 스택 트레이스 가져오기
`debug_getPerformanceStats`	debug	FPS, DrawCall, 메모리 사용량 등 성능 지표 가져오기
`debug_screenshot`	debug	Game/Scene 뷰 스크린샷 캡처 (base64 PNG)
`menu_execute`	editor	경로에 따라 Unity 메뉴 항목 실행
`playmode_control`	editor	PlayMode 상태 진입/종료/조회
`editor_getSelection`	editor	현재 선택된 GameObject 및 Asset 정보 가져오기
`editor_getHierarchy`	editor	씬 GameObject 트리 구조 가져오기 (깊이 제한 가능)
`editor_getProjectStructure`	editor	Assets 디렉토리 구조 가져오기 (깊이 제한 가능)
`editor_getInspector`	editor	선택된 객체의 Inspector 직렬화 필드 값 가져오기
`build_compile`	build	스크립트 컴파일 트리거 및 결과 반환
`build_getCompileErrors`	build	현재 컴파일 오류 목록 가져오기
`build_runTests`	build	Unity Test Runner 테스트 실행 및 결과 반환

설치

Git URL 설치 (권장)

Unity Editor → Window → Package Manager → + → Add package from git URL
다음 URL 입력:

https://github.com/yangfch3/Unity-MCP-Server.git

또는 호스트 프로젝트의 Packages/manifest.json을 직접 편집:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

로컬 경로 설치

본 저장소 클론
Unity Editor → Window → Package Manager → + → Add package from disk
본 저장소 루트 디렉토리의 package.json 선택

또는 Packages/manifest.json에 추가:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "file:../../path/to/unity-mcp"
  }
}

버전 업데이트

UPM을 통해 Git URL로 설치하면 호스트 프로젝트의 packages-lock.json에 현재 커밋 해시가 고정됩니다. 이후 자동으로 업데이트되지 않습니다.

특정 버전을 고정하려면 URL 끝에 Git Tag를 추가할 수 있습니다:

https://github.com/yangfch3/Unity-MCP-Server.git#v0.1.0

해당 Packages/manifest.json 설정:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git#v0.1.0"
  }
}

태그가 없으면 기본 브랜치의 최신 커밋을 추적합니다:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

버전을 업데이트하려면 manifest.json의 #tag 접미사를 새 버전 번호로 수정하거나, UPM GUI에서 다시 Add package from git URL을 선택하여 새 태그 URL을 입력하십시오.

사용법

서비스 시작

Unity Editor → Window → MCP Server
포트 설정(기본값 8090) 후 Start 클릭
패널의 설정 JSON 복사

에이전트 설정

에이전트의 MCP 설정 파일(예: mcp.json)에 다음 내용을 추가하십시오:

{
  "mcpServers": {
    "unity-mcp": {
      "url": "http://localhost:8090/"
    }
  }
}

확장: 사용자 정의 도구 추가

IMcpTool 인터페이스를 구현하고 임의의 Editor 어셈블리에 배치하면 서비스 시작 시 자동으로 발견 및 등록됩니다:

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityMcp.Editor;

public class MyCustomTool : IMcpTool
{
    public string Name => "my_custom_tool";
    public string Category => "custom";
    public string Description => "我的自定义工具";
    public string InputSchema => "{\"type\":\"object\",\"properties\":{}}";

    public Task<ToolResult> Execute(Dictionary<string, object> parameters)
    {
        return Task.FromResult(ToolResult.Success("Hello from custom tool!"));
    }
}

요구 사항

Unity 2022.3+
Editor 환경 전용, 런타임 빌드에 영향 없음

기여

본 프로젝트 개발 참여를 환영합니다. 자세한 내용은 CONTRIBUTING.md를 참조하십시오.

라이선스

MIT

Unity MCP Server