Unity-mcp 연결하기

 오늘은 요즘 Unity 클라이언트 작업을 할 때 알차게 사용하고 있는 Unity-mcp를 통해 Claude Code와 연결해서 Agent를 사용하는 법에 대해서 다뤄볼 것이다. 

 

MCP란?

 MCP(Model Context Protocol)는 AI가 외부 프로그램·데이터·API·파일·DB 같은 도구를 표준화된 방식으로 사용할 수 있게 해주는 통신 규격이다. 쉽게 말하면 AI한테 외부 프로그램 같은 것을 직접적으로 접근해서 파악 및 수정 등을 할 수 있게 도와주는 것이다.

MCP가 왜 필요한가?
 이전의 생성형 AI와 비교하면 이해가 쉽다. 생성형 AI는 사용자가 직접 질문을 하면, 질문한 내용을 분석해서 답변을 생성해준다. 즉, 우리의 프로젝트에 직접 접근하는 것이 아닌 사용자가 질문한 범위 내에서 정보를 얻어야하기 때문에 질문을 정말 잘 적지 않는 이상 높은 품질의 답이 나오기 어려울 수 있다. 

 

 그렇다고 아예 방법이 없던 것은 아니었다. 필요한 프로젝트에 AI가 접근할 수 있게 함수를 만들어주면, AI는 해당 함수를 호출해서 결과를 얻을 수 있었다. 예를 들어 MySQL에 접근하는 함수를 만들어주면, "123번 유저 정보 가져와줘"라는 질문에 AI가 get_user(123) 함수를 호출해 결과를 받아 설명해줄 수 있었다. 문제는 이 함수들이 AI 애플리케이션마다, 도구마다 전부 따로 구현되어야 했다는 점이다. 즉 AI 앱이 N개, 연동할 도구가 M개라면 이론상 N×M번의 통합 작업이 필요했다.

 MCP는 이 문제를 표준 규격으로 해결한다. 도구 제공자가 MCP Server를 표준 프로토콜에 맞춰 한 번만 구현해두면, 이 규격을 지원하는 어떤 AI(MCP Client)든 별도의 커스텀 코드 없이 바로 연동할 수 있다. USB-C가 기기마다 다르던 충전 단자를 하나의 규격으로 통일한 것과 비슷하다. 결과적으로 통합 비용이 N×M에서 N+M 수준으로 줄어든다. 이처럼 MCP는 여전히 함수(Tool) 호출이라는 기본 메커니즘 위에서 동작하지만, 그 호출 방식과 인터페이스를 표준화했다는 점이 핵심이다. 그래서 MCP에서는 어떤 Tool을 어떻게 노출하고 어떤 권한을 부여할지, 즉 Tool 설계와 권한 관리가 매우 중요하다.

 

Unity에 Unity-MCP 적용하기

 이제 Unity에 MCP를 적용해서 AI가 Unity에 접근할 수 있게 만들어보자. 위에서 배운 이론대로 MCP를 적용한 해 놓으면 표준 AI들은 쉽게 연결이 가능하다.

 

 Unity-MCP는 에셋으로도 되어있고 Git URL로도 다운받을 수 있다. 나는 URL로 주로 다운로드 받는 편이다.

 

 구글에 Unity-MCP를 검색하면 github 주소가 나온다.

GitHub - CoplayDev/unity-mcp: Unity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to man

 해당 링크에서 주소를 복사해준다. QuickStart에 있는 주소를 복사해준다.(https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main)

 이후 Unity의 PakageManager에서 해당 주소로 mcp를 install 해준다.

패키지를 다운로드 완료했으면 Window 창에 아래와 같이 MCP가 나오는 것을 볼 수 있다.

Local Setup Window를 눌러서 MCP를 사용하기 위한 조건들을 먼저 확인해야한다.

나는 이전에 설치를 했기 때문에 전부 초록불로 나오지만, 만약 처음한다면 위 파일들을 설치해야될 수 있다. (git도 깔려 있어야한다.)

이후 Next를 눌러서 사용할 AI들을 선택해준다.

나는 클로드만 사용하기에 ClaudeCode만 선택해서 진행했다.

 

필요한 것들을 전부 설치하고 AI도 선택했다면 MCP 서버를 실행시킬 수 있다.

Toggle MCP window를 눌러서 실행 창을 열어준다.

 

Tool에서 AI가 어디까지 접근할 지 권한을 부여할 수 있는데, 나는 Enable All로 모든 권한을 주어서 사용하고 있다. 각자 알맞게 설정해서 사용하면 된다.

 

Connent에서 Transport를 Local로 설정하고, HTTP URL에 로컬 주소를 적어준다.(사진과 같이 적으면 된다.)

이후 Start Server를 눌러서 MCP 서버를 실행시켜준다. 해당 서버가 실행중이어야지만 AI가 유니티에 접근이 가능하다.(해당 서버를 실행시키지 않으면 코드에는 접근이 가능하지만 Unity에는 접근할 수 없다.)

 

성공적으로 실행된다면 아래와 같이 로그가 나올것이다.

만약 Error가 나온다면, 로그를 확인해서 문제를 해결해주면 된다.(설치해야될 파일이 없으면 에러가 뜰 수 있다.)

 

여기까지 완료했다면 Unity에서의 작업은 끝났다. 이제 Visual Studio Code로 가서 Claude Code와 Unity를 연결해주면 된다.

 

Visual Studio Code에서 Unity-MCP 연결하기

 우선 Claude Code CLI를 설치해야한다. CLI는 간단하게 PowerShell에서 설치가 가능하며, 검색하면 빠르게 명령어를 찾을 수 있으니 자세한 내용은 생략하겠다.

 

 Claude Code CLI도 설치했다면 Visual Studio Code에서 가장 먼저 아래 확장팩들을 설치해준다.

이후 Open Floder에서 유니티 프로젝트 폴더를 지정해준다.

그리고 새로운 Terminal을 열어준다.

터미널에 claude라고 치면 Claude에 연결을 시도할 것이다.

/login 명령어를 통해 클로드 코드에 로그인을 해주어야한다.(기간마다 만료가 되기 때문에 만료될때마다 다시 로그인 해줘야하는 불편함이 있다.)

/login 명령어 입력 시 위와 같이 나오는데, 1번을 선택해서 웹에서 클로드 코드를 로그인 시켜서 승인 시킨다.

로그인 완료시 위와 같이 뜨고 Enter를 누르면 완료된다. 아마 처음 로그인하는 환경이면 내용이 더 있을 수 있다.(연결한지 오래 되어서 전부 기억이 나지 않는다..)

 

이후 작업을 시작할 땐 (Unity 프로젝트 창을 다시 킬때) Unity-mcp 서버를 연결하고, visual studio code에서 claude를 쳐서 연결만해준다면 사용할 준비가 완료된다.

 

Claude Code로 작업하기

 다양한 방법이 있겠지만, 나는 매번 작업을 시작하기 전 하는 과정이 있다. 프로젝트 내에서 큰 작업이 끝나고 나면 Claude Code에게 "PROJECT_STRUCTURE.md 파일 최신화해줘" 라고 한다. 해당 파일은 프로젝트를 정리해놓은 파일로, 프로젝트의 구조, 해당 구조로 만든 이유, 구현된 기능 및 연결된 기타 코드들의 내용이 들어있다. Claude Code가 매번 작업하기 전에 프로젝트의 구조를 파악하고 해당 구조를 기반으로 작업을 시키기 위해서 만들었으며, 매번 프로젝트 전체를 읽으며 구조를 파악하지 말고 해당 파일만 읽고 빠르게 구조를 파악하라는 의미로 만들었다. 

 

 이렇게 한번 만들어놓으면 매번 시작할 때 아래와 같이 요청해 빠르게 프로젝트 구조를 파악하게 만들 수 있다.