Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
bridge
bridge
 
 
docs
docs
 
 
examples
examples
 
 
package
package
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.en.md
README.en.md
 
 
README.md
README.md
 
 

Repository files navigation

Unity MCP Agent

English README

Unity MCP Agent는 Unity Editor를 Codex, Claude Code, Antigravity 같은 로컬 AI 에이전트와 연결하는 MCP 서버입니다.

Unity 안에서는 Editor HTTP 서버가 실행되고, AI 툴 쪽에서는 bridge/index.js가 stdio MCP 서버로 동작합니다. AI가 씬 계층 조회, 에셋 검색, 프리팹 배치, 머티리얼/조명/오디오/캐릭터/애니메이션 작업을 Unity Editor에 안전하게 요청할 수 있게 해줍니다.

현재 상태는 개발자/팀 내부 사용을 위한 beta입니다. 로컬에서 신뢰하는 AI 에이전트와 함께 쓰는 용도로 설계되어 있습니다.

구성

UnityMCP/
  package/      Unity Package Manager로 설치하는 Editor 패키지
  bridge/       AI 클라이언트가 실행하는 Node.js MCP stdio bridge
  docs/         설치, Windows, 안전 정책, AI 클라이언트 설정 문서
  examples/     Claude Code, Antigravity 설정 예시

요구사항

  • Unity 2022.3 이상
  • Node.js 18 이상
  • MCP stdio 서버를 지원하는 AI 클라이언트
  • Unity 패키지 의존성: com.unity.nuget.newtonsoft-json

package/package.json에 Newtonsoft Json 의존성이 들어 있으므로, Unity Package Manager로 설치하면 자동으로 함께 잡히는 구성을 목표로 합니다.

빠른 설치

1. Unity 패키지 설치

Git URL로 바로 설치할 수 있습니다.

https://github.com/raindrovvv/UnityMCP.git?path=/package

Unity에서 Package Manager를 열고:

Window > Package Manager > + > Add package from git URL...

위 URL을 붙여 넣으면 됩니다.

로컬에서 받은 폴더를 설치하려면:

Unity에서 Package Manager를 열고:

Window > Package Manager > + > Add package from disk...

그다음 아래 파일을 선택합니다.

/path/to/UnityMCP/package/package.json

설치 후 Unity 메뉴에 아래 항목이 생깁니다.

Window > MCP Agent Server
Tools > Unity MCP > Start Agent Server
Tools > Unity MCP > Stop Agent Server

2. Unity MCP 서버 켜기

Unity에서:

Window > MCP Agent Server

창을 연 뒤 Server Start를 누릅니다.

서버가 켜지면 Unity 프로젝트 안에 토큰 파일이 생성됩니다.

Library/UnityMcpAgent/token.txt

3. AI 클라이언트에 bridge 연결

AI 클라이언트의 MCP 설정에 아래처럼 stdio 서버를 등록합니다.

{
  "command": "node",
  "args": ["/path/to/UnityMCP/bridge/index.js"],
  "env": {
    "UNITY_MCP_PROJECT_ROOT": "/path/to/MyUnityProject",
    "UNITY_MCP_CLIENT_NAME": "Codex"
  }
}

중요한 값은 UNITY_MCP_PROJECT_ROOT입니다. 여기에 Unity 프로젝트 루트를 넣어야 bridge가 Unity에서 생성한 토큰을 읽을 수 있습니다.

Codex 설정 예시

Codex에서 MCP stdio 서버를 추가할 때:

{
  "command": "node",
  "args": ["/Users/me/Project/UnityMCP/bridge/index.js"],
  "env": {
    "UNITY_MCP_PROJECT_ROOT": "/Users/me/UnityProjects/MyGame",
    "UNITY_MCP_CLIENT_NAME": "Codex"
  }
}

Claude Code 설정 예시

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["/Users/me/Project/UnityMCP/bridge/index.js"],
      "env": {
        "UNITY_MCP_PROJECT_ROOT": "/Users/me/UnityProjects/MyGame",
        "UNITY_MCP_CLIENT_NAME": "Claude Code"
      }
    }
  }
}

Antigravity 설정 예시

{
  "command": "node",
  "args": ["/Users/me/Project/UnityMCP/bridge/index.js"],
  "env": {
    "UNITY_MCP_PROJECT_ROOT": "/Users/me/UnityProjects/MyGame",
    "UNITY_MCP_CLIENT_NAME": "Antigravity"
  }
}

연결 테스트

Unity MCP 서버를 켠 뒤 AI에게 아래처럼 요청해보세요.

Unity MCP 도구 목록을 확인하고 echo_test에 "hello unity"를 보내줘.

정상 연결되면 Unity MCP Agent Server 창의 Connected AI Tools 영역에 클라이언트 이름이 표시됩니다.

주요 도구

  • mcp_diagnose: Unity MCP 연결/환경 진단
  • get_scene_hierarchy: 현재 씬 계층 조회
  • search_assets: 프로젝트 에셋 검색
  • modify_scene_object: GameObject 생성/수정/삭제
  • inspect_materials, apply_materials: 머티리얼 조회/적용
  • inspect_lights, upsert_light: 조명 조회/생성/수정
  • inspect_audio_assets: AudioClip, AudioMixer, AudioMixerGroup 조회
  • inspect_audio_sources: 현재 씬의 AudioSource 조회
  • upsert_audio_source: 특정 GameObject에 AudioSource 추가/수정
  • create_audio_emitter: 특정 위치에 3D 사운드 emitter 생성/수정
  • assign_background_music: 씬 BGM AudioSource 생성/수정
  • inspect_characters, place_character: 캐릭터 후보 조회/배치
  • inspect_animation_assets, create_animator_override: 애니메이션 에셋 조회/Override Controller 생성
  • echo_test: 연결 확인용 테스트

오디오 작업 예시

먼저 에셋과 씬 상태를 조회합니다.

Unity MCP로 AudioClip 에셋을 찾아보고, 현재 씬의 AudioSource 목록도 확인해줘.

배경음악은 먼저 계획만 확인합니다.

{
  "tool": "assign_background_music",
  "arguments": {
    "clipPath": "Assets/Audio/BGM/MainTheme.wav",
    "volume": 0.5,
    "dryRun": true
  }
}

3D 효과음은 위치와 거리 감쇠를 함께 지정합니다.

{
  "tool": "create_audio_emitter",
  "arguments": {
    "emitterName": "DoorHum_Audio",
    "clipPath": "Assets/Audio/SFX/DoorHum.wav",
    "positionJson": {"x": 2, "y": 1.5, "z": -4},
    "spatialBlend": 1,
    "minDistance": 1,
    "maxDistance": 12,
    "dryRun": true
  }
}

안전한 사용법

대부분의 변경 도구는 기본값이 dryRun=true입니다.

권장 흐름:

  1. 조회 도구로 현재 상태를 확인합니다.
  2. 변경 도구를 dryRun=true로 호출해서 계획만 확인합니다.
  3. 결과가 맞으면 같은 요청에 dryRun=false를 넣어 적용합니다.
  4. 씬 저장이 필요할 때만 saveScene=true를 사용합니다.

이 도구는 로컬 개발 자동화 도구입니다. Unity MCP HTTP 서버를 외부 네트워크에 노출하지 마세요.

Windows에서 서버 시작이 안 될 때

Windows에서 Access is denied 또는 URL 권한 오류가 나면 PowerShell을 관리자 권한으로 열고 아래 명령을 한 번 실행하세요.

netsh http add urlacl url=http://localhost:24892/ user=%USERNAME%
netsh http add urlacl url=http://127.0.0.1:24892/ user=%USERNAME%

그 다음 Unity MCP 서버를 다시 시작하면 됩니다.

포트를 바꿨다면 24892를 실제 포트로 바꾸세요.

환경 변수

  • UNITY_MCP_PROJECT_ROOT: Unity 프로젝트 루트. bridge가 패키지 밖에 있을 때 필요합니다.
  • UNITY_MCP_PORT: Unity HTTP 서버 포트. 기본값은 24892.
  • UNITY_MCP_TOKEN: 토큰 파일 대신 직접 토큰을 지정합니다.
  • UNITY_MCP_TOKEN_FILE: 토큰 파일 경로를 직접 지정합니다.
  • UNITY_MCP_CLIENT_NAME: Unity 창에 표시될 클라이언트 이름.
  • UNITY_MCP_TOOLS_TIMEOUT_MS: 도구 목록 조회 timeout. 기본값은 1000.
  • UNITY_MCP_EXECUTE_TIMEOUT_MS: 도구 실행 timeout. 기본값은 30000.

자세한 문서

라이선스

MIT License. 자세한 내용은 LICENSE를 확인하세요.

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages