Unity AI 입문 2: MCP for Unity 10.3.0을 설치하고 Cursor에 연결하기
정확한 Git URL, Python·uv 준비, HTTP Local 서버, Cursor 설정과 읽기 전용 연결 확인을 순서대로 설명해요.
마지막 업데이트
메뉴나 지원 기능이 달라졌다면 아래 자료 확인일과 현재 앱 버전을 함께 봐주세요.

대표 화면은 공식 저장소에 포함된 v8.6 예시예요. 현재 10.3.0의 직접 촬영 화면이 아니에요. MIT · Media credits
이번 목표는 Cursor의 AI가 현재 Unity 장면 정보를 읽는 것이에요. 상자를 만들기 전에 연결부터 확인하면, 문제가 AI 요청·서버·에디터 중 어느 쪽에 있는지 나눠볼 수 있어요. 이 글의 에디터 조작은 10.3.0 공식 소스 기반 안내이며, 범블비가 Unity와 Cursor를 실제로 연결한 기록은 아니에요. 서버 자체의 제한된 실행 확인은 소개편에 따로 적었어요.
1. 연습 프로젝트와 필요한 프로그램을 준비해요
Unity Editor와 사용 가능한 라이선스, 로그인해 AI 기능을 사용할 수 있는 Cursor를 먼저 준비해요. Unity가 처음이면 설치·첫 장면 준비를 따라가세요. 원본 게임 대신 별도 프로젝트를 열고, 열려 있는 에디터는 우선 하나로 줄여요. 현재 장면을 저장한 경로도 적어두세요.
Git URL 설치에는 Git이 필요해요. Git 공식 다운로드에서 운영체제에 맞게 설치한 뒤 새 터미널에서 git --version을 확인해요. uv는 Python 실행 환경과 패키지를 준비하는 도구예요. 공식 uv 설치 안내의 운영체제별 방법 중 하나를 선택해요. Windows에서 WinGet을 사용한다면 다음 명령, macOS에서 Homebrew를 이미 사용한다면 그다음 명령을 각각 사용해요. 두 운영체제의 명령을 모두 실행하는 것이 아니에요.
winget install --id=astral-sh.uv -e
brew install uv
터미널을 다시 열어 uv --version이 응답하는지 확인해요. Python이 없다면 uv python install 3.12로 준비하고 uv python list에서 설치 상태를 확인할 수 있어요. 3.12는 이 가이드의 구체적인 예시이며 공식 최소 조건은 Python 3.10 이상이에요. 회사가 관리하는 컴퓨터라면 설치 제한을 무시하지 말고 허용된 환경을 사용해요. Python 관리 안내
2. 정확한 패키지 주소를 추가해요
화면에서 확인: Unity 상단 메뉴에서 Package Manager를 열면 패키지 목록과 추가 메뉴가 보여요. Git URL 입력란에 주소를 넣은 후 가져오기가 끝날 때까지 기다리고, 목록의 패키지 이름과 버전을 확인하세요. 창 모양이나 + 위치는 Editor 버전에 따라 달라질 수 있어요.
Unity의 Window → Package Manager에서 **+ → Add package from git URL…**로 들어가 아래 주소를 넣어요. ?path=/MCPForUnity는 저장소 안의 Unity 패키지 위치, #v10.3.0은 이 과정에서 확인한 릴리스예요.
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.3.0
설치 후 목록에서 MCP for Unity와 버전 10.3.0을 확인하고, Unity가 패키지 가져오기와 컴파일을 끝낼 때까지 기다려요. 오류가 있으면 다음 설정을 덧붙이기 전에 Console의 첫 오류를 남겨요. 공식 README의 간단한 설치 문장에는 예전 버전 핀 예시도 남아 있어, 이 글은 릴리스 태그와 package.json을 맞춘 주소를 사용해요. 고정한 설치 문서
3. MCP 창에서 로컬 서버를 시작해요
처음 가져올 때 setup wizard가 열리면 Python·uv 의존성 상태를 확인해요. 모두 준비된 상태에서 Done을 누르고 감지된 클라이언트 중 Cursor를 선택해 Configure Selected로 설정할 수 있어요. 다시 설정할 때는 Window → MCP for Unity에서 창을 열어요.
Connection의 transport는 HTTP Local을 사용해요. 로컬 HTTP 주소는 http://localhost:8080처럼 같은 컴퓨터를 가리키게 해요. Start Server를 누르면 서버 실행과 세션 시작을 시도하는 구조예요. 서버는 실행됐는데 세션이 연결되지 않으면 현재 상태와 로그를 확인하고, 연결 버튼이 표시되는 상태라면 Connect로 연결을 확인해요. 이 버튼 동작은 해당 버전의 연결 코드와 대조했어요. 다른 컴퓨터 공개 서버를 여는 HTTP Remote 설정은 이번 과정의 범위가 아니에요.

공식 예시 화면의 명령에는 개발자 컴퓨터 경로가 들어 있어요. 그대로 복사하지 말고 자신의 창에서 생성된 값과 설치 버전을 확인하세요. 서버 주소 자체와 MCP 요청 주소도 구분해요. 이 로컬 예시에서 클라이언트가 요청할 주소는 끝에 /mcp가 붙은 http://localhost:8080/mcp예요.
4. Cursor에서 서버 설정을 확인해요
화면에서 확인: MCP 창의 서버 상태와 Unity 연결 상태를 각각 확인하세요. 위 v8.6 개발자 화면은 위치를 익히는 참고 자료이며 10.3.0의 버튼 배치나 연결 성공을 보증하지 않아요.
자동 설정을 썼다면 Cursor의 MCP 목록에서 unityMCP 항목과 활성 상태를 확인해요. 프로젝트 문서의 예전 설정 메뉴명과 현재 Cursor UI가 다를 수 있어, 확인일의 Cursor 공식 안내는 사이드바 Customize에서 서버를 관리하도록 설명해요. 서버를 활성화하고 새 대화를 열어 도구 목록을 다시 확인해요.
수동으로 설정한다면 해당 프로젝트의 .cursor/mcp.json에 아래 구성을 사용할 수 있어요. 전역 설정은 사용자 홈의 ~/.cursor/mcp.json이며 적용 범위가 달라요. 기존 서버가 이미 있으면 파일 전체를 덮어쓰지 말고 mcpServers 안에 항목을 합쳐야 해요. 이미 자동 등록된 항목을 다른 이름으로 중복 추가하지도 않아요.
{
"mcpServers": {
"unityMCP": {
"url": "http://localhost:8080/mcp"
}
}
}
이 예시는 Cursor용이에요. VS Code의 servers 구조나 Claude Desktop용 stdio 실행 구성을 같은 JSON으로 착각하지 마세요. 사용 클라이언트를 바꿀 때는 해당 구성기로 다시 확인해요.
5. 변경 없는 요청으로 마지막 연결을 확인해요
Cursor 확인 순서: MCP 서버 목록에서 unityMCP를 열어 활성화 상태와 도구 목록을 확인한 다음 새 채팅에서 읽기 요청을 보내요. 승인창이 나오면 조회 대상과 인수를 보고 승인하세요. 반환된 장면 이름·경로가 Unity의 현재 장면과 일치하는지까지 봐야 해요. 색상이나 문구만으로 성공을 판단하지 마세요.
Cursor에서 현재 Unity 장면의 이름·경로를 읽도록 요청하고 도구 호출의 이름과 인수를 펼쳐봐요. 예를 들어 manage_scene의 action: get_active를 사용하는 조회예요. 장면을 만들거나 삭제할 필요가 없어요. 승인 요청이 나타나면 실제로 조회만 하는지 확인하고 진행해요.
반환된 장면 이름이 Unity에서 열어둔 것과 같은지 대조해요. 도구 목록이 보이는 것, 서버 상태가 정상인 것, Unity 장면의 실제 정보가 돌아오는 것은 세 가지 다른 확인이에요. 이 마지막 조회가 성공해야 이번 연결 목표를 완료한 것으로 적어요. 반환 메시지가 에디터를 못 찾았다고 말하면 연결 완료가 아니에요.
완료 메모에는 에디터 버전, 패키지 10.3.0, 선택한 클라이언트, HTTP 주소, 반환된 장면 경로를 적어요. 비밀키를 메모나 공개 캡처에 넣을 필요는 없어요. 다음에는 같은 연결에서 상자를 생성하고 저장·재열기까지 확인해요.
다음 단계: 3. AI로 첫 장면 만들기.
참고 자료
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/MCPForUnity/package.json
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/install.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/clients.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/first-prompt.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/manage_scene.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/manage_gameobject.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/read_console.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/guides/troubleshooting.md
- https://github.com/CoplayDev/unity-mcp/releases/tag/v10.3.0
- https://cursor.com/docs/mcp
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/LICENSE