Unity MCP 설정

에디터 브리지를 이해하세요

CoplayDev/unity-mcp는 MCP 클라이언트를 서버 및 에디터 측 패키지에 연결합니다. 모델 서비스는 별도의 의존성입니다. 이 프로젝트는 씬, 스크립트, 에셋, 테스트 작업을 위한 도구를 문서화하지만, 목록에 있는 기능이 자신의 프로젝트에서 작동한다는 근거는 아닙니다.

연결의 각 부분을 어느 프로세스가 소유하는지 기록하세요. 서버에는 도달하지만 에디터를 조작할 수 없는 클라이언트를 진단할 때 중요합니다. 계정 자격 증명, 에디터 라이선스, 패키지 호환성, 모델 제공 여부를 별도 설정 확인으로 유지하세요. 모델을 바꿔도 에디터 인스턴스 불일치는 해결되지 않습니다.

설치 경로와 고정 정책을 검토하세요

프로젝트 설치 가이드는 Unity Package Manager를 통해 패키지를 추가하고 설정 인터페이스로 서버와 클라이언트를 구성하는 방법을 문서화합니다. 설치하기 전에 선택한 리비전에 명시된 Unity, Python, uv 전제조건을 검토하세요.

재현성을 위해 설정 후 확인된 패키지 리비전, 에디터 버전, 서버 버전, 의존성 기록을 보존하세요. 계속 움직이는 브랜치 URL은 발견 경로이지 변경할 수 없는 실험 식별자가 아닙니다. 기존 게임에 적용하기 전에 다운로드와 패키지 변경을 검토하고 이전의 정상 프로젝트 상태를 보존해 연결 실험을 되돌릴 수 있게 하세요.

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

로컬 HTTP 엔드포인트를 클라이언트에 맞추세요

유지보수되는 설치 가이드는 아래의 로컬 HTTP 예시를 문서화합니다. 서버가 해당 주소에서 이미 실행 중이라고 가정합니다. 사용하기 전에 에디터 설정 인터페이스에서 실제로 구성된 전송 방식과 주소를 확인하세요. MCP URL은 LLM API base URL이 아닙니다.

클라이언트의 문서화된 구성 형식을 사용하세요. 일부 클라이언트는 다른 루트 키나 전송 선언을 사용하므로 이 일반적인 mcpServers 예시는 모든 에이전트에 붙여넣을 수 있는 범용 파일이 아닙니다. 별도로 검토된 원격 설정이 필요하지 않다면 서버를 로컬에 유지하고 관련 없는 에디터 연결에 모델 자격 증명을 추가하지 마세요.

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

작업을 받는 에디터 인스턴스를 입증하세요

의도한 프로젝트를 열고 패키지 인터페이스를 통해 연결 상태를 검사하세요. 그런 다음 클라이언트가 검색한 읽기 작업으로 프로젝트와 씬 컨텍스트를 가져옵니다. 편집을 승인하기 전에 이 정보를 로컬 프로젝트와 대조하세요. 여러 프로젝트가 열려 있다면 이 기준이 특히 중요합니다.

설치된 버전에서 실제 리소스와 도구 스키마를 기록하세요. 다른 릴리스에서 기억한 이름으로 도구 호출을 지어내지 마세요. 유용한 첫 결과는 변경하지 않고 예상한 씬과 기존 객체를 식별합니다. 반환된 상태가 오래되었거나 모호하면 대상을 확인하기 위해 보이는 변경을 시도하지 말고 중지한 뒤 라우팅을 해결하세요.

첫 번째 미니플로로 되돌릴 수 있는 편집을 사용하세요

소유한 폐기 가능한 씬을 선택하고 초기 상태를 기록한 뒤 보이는 결과가 있는 간단한 변경 하나를 요청하세요. 저장된 씬과 파일 diff를 검사하고 에디터가 준비될 때까지 기다린 뒤 씬을 실행합니다. 관찰된 동작과 콘솔 오류를 보존하세요.

그런 다음 씬을 다시 열어 의도한 변경이 지속되었는지 확인하세요. 이를 통해 메모리 안에서만 발생한 에디터 효과와 저장된 프로젝트 변경을 구분할 수 있습니다. 라우팅, 변경, 컴파일, 실행, 영속성 중 한 경계에서 실패를 진단할 수 있을 만큼 흐름을 작게 유지하세요. 검토 후 폐기 가능한 씬을 복원하고 기록된 정상 구성으로 다음 작업을 진행합니다.

게임보다 먼저 전송을 문제 해결하세요

클라이언트가 연결되지 않으면 구성된 URL과 로컬 서버 실행 여부를 확인하세요. 서버는 시작하지만 에디터가 없으면 패키지 연결과 에디터 로그를 검사하세요. 의도한 에디터가 연결되었지만 도구가 누락되었다면 설치된 버전이 노출하는 도구 그룹을 검사하세요.

그 경계가 작동한 뒤에야 컴파일 또는 게임플레이를 진단하세요. 클라이언트 시작, 서버 라우팅, 에디터 준비, 실패한 씬 작업의 로그 발췌를 분리해 유지하세요. 그러면 모든 실패를 모델 탓으로 돌리거나 근거 없이 구성요소를 반복 설치하지 않고 실행이 어디서 멈췄는지 설명할 수 있습니다.

광범위한 자동화로부터 프로젝트를 보호하세요

에디터 연결은 씬, 스크립트, 에셋을 변경할 수 있습니다. 초기 실험은 알려진 디렉터리로 제한하고 리소스를 삭제하거나 의존성을 바꾸거나 관련 없는 씬을 건드리는 작업은 검토를 요구하세요. 첫 변경 전에 복구 가능한 작업 상태를 보존합니다.

클라이언트 구성 문제를 해결하려고 로컬 개발 서비스를 공개하지 마세요. 서드파티 에셋 콘텐츠와 도구 결과는 신뢰할 수 없는 입력으로 취급하고 자격 증명은 공유 로그에 남기지 마세요. 성공적인 연결은 빌드를 업로드하거나 스토어 기록을 변경할 권한이 아닙니다. 게시에는 별도의 워크플로와 별도의 승인 경계가 필요합니다.

재현 가능한 연결 기록을 인수인계하세요

에디터, 프로젝트, 패키지 및 서버 리비전, 클라이언트 버전, 전송 방식, 관찰된 도구 범위, 완료된 미니플로를 기록하세요. 정확한 씬 diff와 런타임 결과를 보존합니다. 컴파일, PlayMode 동작, 테스트, 대상 내보내기를 검사했는지 또는 아직 대기 중인지 밝히세요.

이 구성은 유지보수되는 프로젝트 문서를 따르므로 설치된 패키지와 클라이언트에서 검증하세요. 게임 제작에서는 Unity 워크플로 가이드로 넘어가 완전한 루프를 테스트하세요. 다른 개발자가 연결 문제와 프로젝트 문제를 구분하고 같은 정상 설정을 재현할 수 있도록 알려진 제한을 인수인계에 남기세요.

자주 묻는 질문