유니티-MCP

MCP(Model Context Protocol)를 사용하여 Unity와 AI 어시스턴트를 연결합니다.

개요

Unity-MCP는 Unity 게임 개발을 위한 모델 컨텍스트 프로토콜(Model Context Protocol)의 오픈 소스 구현입니다. AI 어시스턴트가 표준화된 인터페이스를 통해 Unity 게임 환경과 상호 작용할 수 있도록 지원하여 AI 지원 게임 개발, 자동 테스트, 장면 분석 및 런타임 디버깅을 가능하게 합니다.

건축학

AILogger를 사용하여 지속성을 유지하도록 아키텍처가 간소화되어 별도의 서버 구성 요소가 필요 없게 되었습니다.

지엑스피1

AI Assistant : MCP 프로토콜을 사용하여 Unity-MCP STDIO 클라이언트와 통신합니다.
Unity-MCP STDIO 클라이언트 : Unity 클라이언트에 명령을 전달하고 결과를 AILogger에 저장합니다.
Unity 클라이언트 : Unity에서 명령을 실행하고 결과를 반환합니다.
AILogger : 나중에 검색할 수 있도록 로그와 결과를 저장합니다.

Unity-MCP STDIO 클라이언트는 코드 실행과 쿼리 모두에 대한 엔드포인트를 제공하는 Unity 클라이언트와 직접 통신합니다. 쿼리 도구는 쿼리를 return 문으로 래핑하여 코드 실행으로 변환합니다.

특징

Unity 런타임 환경에서 C# 코드 실행
게임 객체와 그 구성 요소를 검사합니다
장면 계층 구조 및 구조 분석
테스트를 실행하고 결과를 받습니다.
게임 객체 및 구성 요소에 대한 메서드 호출
런타임 중 게임 상태 수정

배포 옵션

Unity Editor 확장: 게임 실행 주기를 넘어 지속되는 Editor 확장
Docker 컨테이너: 네트워크를 통해 Unity와 통신하는 컨테이너화된 버전
NPX 패키지: NPX를 통해 설치 및 실행할 수 있는 Node.js 패키지

선적 서류 비치

MCP 아키텍처 : MCP 아키텍처 및 네임스페이스 개요
MCP STDIO 클라이언트 : MCP STDIO 클라이언트 및 로깅 기능에 대한 정보
쿼리 도구 : 쿼리 도구와 그 작동 방식에 대한 자세한 정보
AILogger 통합 : AILogger 통합에 대한 자세한 정보
API 참조 : API 엔드포인트에 대한 자세한 정보
설치 가이드 : Unity-MCP 설치 및 설정을 위한 단계별 지침
개발 가이드 : 개발 환경 및 워크플로에 대한 정보
핫 리로딩 가이드 : 개발 환경에서 핫 리로딩에 대한 자세한 정보
핫 리로딩 빠른 참조 : 핫 리로딩 명령 및 팁에 대한 빠른 참조 가이드
기여 가이드 : 프로젝트 기여를 위한 가이드라인

시작하기

Unity-MCP를 시작하려면 다음 단계를 따르세요.

저장소를 복제합니다.
git clone https://github.com/TSavo/Unity-MCP.git cd Unity-MCP
종속성 설치:
npm install
프로젝트를 빌드하세요:
npm run build
MCP STDIO 클라이언트를 시작합니다.
npm start
이렇게 하면 Unity와 통신하고 지속성을 위해 AILogger를 사용하는 MCP STDIO 클라이언트가 시작됩니다.참고: AILogger가 http://localhost:3030 에서 실행 중인지 확인하거나 AI_LOGGER_URL 환경 변수를 설정하여 AILogger 인스턴스를 가리키도록 하세요.
테스트 실행:
# Run all tests npm test # Run only unit tests npm run test:unit # Run only e2e tests npm run test:e2e # Run tests with a specific pattern npm test -- --testNamePattern="should return the server manifest" npm run test:unit -- --testNamePattern="should return the server manifest" npm run test:e2e -- --testNamePattern="should discover the test server"

자세한 지침은 설치 가이드를 참조하세요.

AI 어시스턴트에 연결

Unity-MCP 브리지를 AI 어시스턴트에 연결하려면 MCP 구성 파일을 만들어야 합니다.

{
  "mcpServers": {
    "unity-ai-bridge": {
      "url": "http://localhost:8080/sse"
    }
  }
}

이 파일을 AI 비서의 적절한 위치에 저장하세요. Claude의 경우, 일반적으로 Claude Desktop 앱의 구성 디렉터리에 저장됩니다.

사용 가능한 도구

Unity-MCP 브리지는 다음과 같은 도구를 제공합니다.

execute_code : Unity에서 C# 코드를 직접 실행합니다.
쿼리 : 점 표기법을 사용하여 쿼리를 실행하여 객체, 속성, 메서드에 액세스합니다.
get_logs : AILogger에서 로그를 검색합니다.
get_log_by_name : AILogger에서 특정 로그를 검색합니다.

사용 예

Unity에서 코드 실행

Unity에서 execute_code 도구를 사용하여 C# 코드를 실행할 수 있습니다. 코드는 Unity 런타임 환경에서 실행되며, 결과는 나중에 검색할 수 있도록 AILogger에 저장됩니다.

JSON-RPC 요청

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
      "timeout": 5000
    }
  }
}

JSON-RPC 응답

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
      }
    ]
  }
}

Unity 객체 쿼리

query 도구를 사용하여 Unity 객체를 쿼리할 수 있습니다. 이를 통해 점 표기법을 사용하여 객체, 속성 및 메서드에 액세스할 수 있습니다.

JSON-RPC 요청

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "Camera.main.transform.position",
      "timeout": 5000
    }
  }
}

JSON-RPC 응답

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
      }
    ]
  }
}

AILogger에서 결과 검색

get_log_by_name 도구를 사용하면 AILogger에서 이전 작업의 결과를 검색할 수 있습니다.

JSON-RPC 요청

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_log_by_name",
    "arguments": {
      "log_name": "unity-execute-1712534400000",
      "limit": 1
    }
  }
}

JSON-RPC 응답

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
      }
    ]
  }
}

사용 예

AI 어시스턴트가 Unity 도구에 액세스하면 다음과 같은 작업을 수행하도록 요청할 수 있습니다.

Can you execute the following C# code in Unity?

GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);

특허

MIT

작가

T 사보( @TSavo )

Unity-MCP

Integrations

유니티-MCP

개요

건축학

특징

배포 옵션

선적 서류 비치

시작하기

AI 어시스턴트에 연결

사용 가능한 도구

사용 예

Unity에서 코드 실행

JSON-RPC 요청

JSON-RPC 응답

Unity 객체 쿼리

JSON-RPC 요청

JSON-RPC 응답

AILogger에서 결과 검색

JSON-RPC 요청

JSON-RPC 응답

사용 예

특허

작가

Tools

Related Resources