문제 해결

이 페이지는 Unity MCP에서 가장 자주 발생하는 문제와 해결 방법을 정리합니다. 먼저 빠른 점검 목록을 확인하고, 그래도 해결되지 않으면 아래에서 해당 증상을 찾아보세요.

빠른 점검 목록#

1. Window > AI Game Developer — MCP를 열고 타임라인을 확인하세요. Unity, MCP server, AI agent가 모두 초록색이어야 합니다.
2. Unity Console에서 오류를 확인하세요. 프로젝트 어디에서든 컴파일 오류가 있으면 플러그인의 에디터 스크립트가 로드되지 않습니다.
3. unity-mcp-cli status ./MyUnityProject를 실행해 Unity가 실행 중인지, 어떤 서버에 연결할 수 있는지 확인하세요.
4. 설정을 변경한 뒤에는 항상 AI 클라이언트를 재시작하세요.
5. 플러그인과 확장 기능이 최신 버전인지 확인하세요.

AI 클라이언트에 Unity 도구가 표시되지 않음#

• Unity가 준비되기 전에 클라이언트가 연결된 경우. 클라이언트에서 MCP 서버를 다시 연결하거나(Claude Code에서는 /mcp), 창에 Connected가 표시된 후 클라이언트를 재시작하세요.
• 클라이언트가 구성되지 않았거나 이전 구성을 사용하는 경우. 창에서 해당 에이전트의 Configure(또는 Reconfigure)를 클릭하거나 unity-mcp-cli setup-mcp <agent> .를 실행한 뒤 클라이언트를 재시작하세요.
• 클라우드 모드에 로그인하지 않은 경우. 창에 "Authorization Required"가 표시됩니다. Authorize를 클릭하고 브라우저에서 코드를 승인하세요.
• 여러 프로젝트가 열려 있는 경우. 고정되지 않은 https://ai-game.dev/mcp URL은 다른 에디터로 라우팅될 수 있습니다. Configure가 기록하는 고정 URL을 사용하세요.
• 에이전트를 다른 폴더에서 시작한 경우. .mcp.json이나 .cursor/mcp.json 같은 프로젝트 수준 구성은 클라이언트가 Unity 프로젝트 폴더에서 실행될 때만 읽힙니다.
• VS Code에서는 Copilot Chat을 Agent 모드로 전환하세요.

클라우드 로그인 문제#

• "Authorization Required"가 계속 표시되는 경우. 자격 증명이 만료되었거나 취소되었습니다. Authorize를 다시 클릭하거나 unity-mcp-cli login --force를 실행하세요.
• "Connection Required". 로그인은 되었지만 Unity가 연결되지 않았습니다. Connect를 클릭하세요.
• 잘못된 계정으로 로그인한 경우. Revoke를 클릭한 뒤(이 작업은 해당 머신의 모든 AI Game Dev 도구에서 로그아웃합니다) 올바른 계정으로 Authorize하세요. unity-mcp-cli login은 계정을 전환하기 전에 확인을 요청합니다.

계정의 세션 및 기기 관리는 Authentication에 설명되어 있습니다.

로컬 MCP 서버가 시작되지 않음 (Custom 모드)#

• 바이너리가 다운로드되지 않은 경우. 바이너리는 Library/mcp-server/<platform>/에 저장됩니다. 다운로드가 실패하면(오프라인, 방화벽, 프록시) 창에 "Server binary error"와 Download / Retry server 버튼이 표시됩니다. Tools > AI Game Developer > Server > Download Binaries를 사용할 수도 있습니다.
• 백신이 실행 파일을 차단한 경우. 보안 소프트웨어에서 gamedev-mcp-server를 허용한 뒤 다시 시도하세요.
• 전송 방식이 stdio인 경우. stdio에서는 AI 에이전트가 서버를 직접 시작하므로 Start 버튼이 비활성화됩니다. Unity가 서버를 실행하도록 하려면 http로 전환하세요.
• 서버 로그를 확인하세요. Tools > AI Game Developer > Server > Open Logs와 Open Log Errors를 사용하세요.
• 서버를 직접 테스트하세요. Tools > AI Game Developer > Server > Launch MCP Inspector는 로컬 서버에 대해 MCP Inspector를 엽니다(HTTP 전송만 지원하며 Node.js가 필요합니다).

포트 충돌#

각 프로젝트에는 경로에서 파생된 20000~29999 사이의 고정 포트가 할당됩니다. 다른 프로세스가 이미 해당 포트를 사용 중이면 창에 MCP 서버가 External로 표시됩니다. 해당 프로세스를 찾으세요.

netstat -ano | findstr :<port>

lsof -i :<port>

그 프로세스를 중지하거나, 연결을 끊고 Server URL에 다른 포트(예: http://localhost:25000)를 입력한 뒤 Configure를 다시 클릭해 에이전트가 새 포트를 사용하도록 하세요.

컴파일 중 연결 끊김#

Unity는 코드가 변경될 때마다, 그리고 Play 모드로 전환할 때 스크립트를 다시 로드합니다. 플러그인은 다시 로드 전에 연결을 끊고 이후에 다시 연결하므로 잠시 "Disconnected" 또는 "Connecting..."이 표시되는 것은 정상입니다. 다시 로드 중에 진행 중이던 도구 호출은 실패할 수 있으니 에이전트에게 다시 시도하도록 요청하세요.

설치 후 컴파일 오류 또는 DLL 누락#

플러그인은 .NET 종속성을 NuGet에서 Assets/Plugins/NuGet으로 다운로드합니다.

• McpPlugin, ReflectorNet 또는 SignalR에서 형식을 찾을 수 없다는 오류. 첫 가져오기가 끝날 때까지 기다린 뒤 Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs를 사용하세요.
• Windows에서 "Path too long". Unity 런타임은 긴 경로가 활성화되어 있어도 Windows의 260자 경로 제한을 넘는 DLL을 열 수 없습니다. 프로젝트를 C:/Projects/MyGame처럼 더 짧은 폴더로 옮기세요.
• 완전 재설치. Unity를 닫고 Assets/Plugins/NuGet 및 해당 .meta 파일을 삭제한 뒤 프로젝트를 다시 여세요.

공백이 포함된 프로젝트 경로#

Console에 "The project path contains spaces"가 표시되면 프로젝트를 공백이 없는 폴더로 옮기세요. 이런 경로는 사용 중 문제를 일으킬 수 있어 플러그인이 경고합니다.

도구 호출 실패 또는 시간 초과#

• "object not found" 같은 오류. 이름이나 경로를 추측하지 말고 에이전트에게 먼저 조회하도록(예: rql-query) 요청하세요. 에셋 경로는 Assets/로 시작합니다.
• 긴 작업이 시간 초과되는 경우. 느린 베이크나 대규모 테스트 실행을 위해 창에서 Tool timeout (ms)(기본값 300000)을 늘리세요.
• 배치 모드에서 스크린샷이 실패하는 경우. -nographics로 시작된 에디터에는 그래픽 장치가 없습니다. -nographics 없이 헤드리스로 시작하세요. unity-mcp-cli open --headless는 이미 그렇게 합니다.
• 사용자 정의 도구가 스레드 오류를 발생시키는 경우. Unity API 호출을 MainThread.Instance.Run으로 감싸세요. Custom tools를 참고하세요.

unity-mcp-cli 문제#

• open이 "Enter Safe Mode?"에서 멈추는 경우. CLI가 자동으로 Ignore를 클릭합니다. macOS에서는 터미널에 손쉬운 사용 권한을 부여하고, Linux에서는 xdotool을 설치하세요.
• exec가 대기하다가 포기하는 경우. CLI가 시작하지 않은 에디터에서 프로젝트가 열려 있고 해당 플러그인이 로컬에서 응답하지 않는 경우입니다(예: 클라우드에 연결됨). 플러그인을 연결하거나, Custom으로 전환하거나, --url을 전달하세요.
• setup-skills가 실패하는 경우. 플러그인이 연결된 실행 중인 에디터가 필요합니다. 먼저 open과 wait-for-ready를 실행하세요.
• 자세한 로그를 보려면 아무 명령에나 --verbose를 사용하세요.

완전 초기화#

1. Unity를 닫습니다.
2. 프로젝트의 Library/mcp-server/를 삭제합니다.
3. Unity를 다시 열고 Tools > AI Game Developer > Reset Config를 선택합니다.
4. 다시 로그인하거나(Cloud) 서버를 시작한 뒤(Custom) 에이전트에 대해 Configure를 클릭합니다.
5. AI 클라이언트를 재시작합니다.

도움 받기#

AI Game Developer 창 하단의 Help / Talk(Discord) 또는 Bug Report(GitHub issues)를 사용하세요. Unity 버전, OS, 플러그인 버전(창에 표시됨), Console의 오류, 재현 단계를 포함하세요. FAQ 또는 사이트 전체 FAQ를 찾아볼 수도 있습니다.