# 문제 해결 — Unity · AI Game Developer Wiki

Unity MCP의 흔한 문제 해결 - AI 클라이언트에 도구가 표시되지 않음, 로그인 및 연결 오류, 서버 다운로드 실패, NuGet DLL 오류, 포트 충돌.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unity/troubleshooting).

이 페이지는 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](https://ai-game.dev/docs/auth)에 설명되어 있습니다.

## 로컬 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**로 표시됩니다. 해당 프로세스를 찾으세요.

```powershell
netstat -ano | findstr :<port>
```

```bash
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](https://ai-game.dev/ko/docs/wiki/unity/custom-tools#main-thread)를 참고하세요.

## 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](https://ai-game.dev/ko/docs/wiki/unity/faq) 또는 사이트 전체 [FAQ](https://ai-game.dev/docs/faq)를 찾아볼 수도 있습니다.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unity/troubleshooting

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unity/troubleshooting