Unity MCP 서버

中文 | English

MCP (Model Context Protocol)를 통해 Unity Editor 기능을 외부 AI 에이전트에 노출하는 Unity Editor 플러그인입니다.

에이전트(예: Kiro, Cursor, Claude Code)는 표준 MCP 프로토콜을 통해 Unity Editor에 연결하여 에디터 기능을 호출할 수 있습니다.

철학

본 플러그인은 AI 에이전트를 위한 Unity 인식 계층 + 진단 도구 체인으로 포지셔닝됩니다:

• 인식 우선 — '씬 상태 읽기, 컨텍스트 가져오기, 진단 보조'와 같은 고빈도 시나리오를 우선적으로 다루어, 에이전트가 현재 프로젝트 상태를 충분히 이해하고 개발 의사결정을 보조할 수 있도록 합니다.

• 구조화된 쓰기 — 안전하고 감사 가능한 쓰기 작업 기능(예: 속성 수정, 노드 추가/삭제)을 제공하지만, Unity Editor GUI의 모든 상호작용을 커버하는 것을 목표로 하지는 않습니다.

• 에디터를 대체하지 않음 — 엔지니어와 에이전트 간의 협업 효율성을 높이는 것이 목표이며, 에디터의 모든 작업을 대화창으로 옮기는 것이 아닙니다.

Related MCP server: MCP Unity

특징

• Streamable HTTP 전송 — MCP 2025-03-26 사양 기반, 단일 HTTP 엔드포인트

• 프로세스 내 실행 — 외부 Node.js/Python 프로세스 없이 에디터 내에서 직접 시작

• 확장 가능한 도구 시스템 — IMcpTool 인터페이스를 구현하여 새 도구를 등록할 수 있으며, 핵심 코드 수정 불필요

• Domain Reload 자동 복구 — PlayMode 진입/종료 후 서비스 자동 재시작

내장 도구

전체 매개변수 설명 및 사용 예시는 도구 상세 문서를 참조하세요.

디버그 도구

에디터 도구

Query (조회)

Mutation (수정)

프로젝트 (Project)

에셋 (Asset)

빌드 도구

코드 도구 (실험적, Unity 2022 Mono 전용)

Window → MCP Server 패널에서 수동으로 활성화해야 합니다. 자세한 내용은 도구 상세 문서를 참조하세요.

설치

Git URL 설치 (권장)

1. Unity Editor → Window → Package Manager → + → Add package from git URL

2. 다음 URL 입력:

https://github.com/yangfch3/Unity-MCP-Server.git

또는 호스트 프로젝트의 Packages/manifest.json을 직접 편집:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

로컬 경로 설치

1. 본 저장소 클론

2. Unity Editor → Window → Package Manager → + → Add package from disk

3. 본 저장소 루트 디렉토리의 package.json 선택

또는 Packages/manifest.json에 추가:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "file:../../path/to/unity-mcp"
  }
}

버전 업데이트

UPM을 통해 Git URL로 설치하면 호스트 프로젝트의 packages-lock.json에 현재 커밋 해시가 고정됩니다. 이후 자동으로 업데이트되지 않습니다.

특정 버전을 고정하려면 URL 끝에 Git Tag를 추가할 수 있습니다:

https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.0

해당 Packages/manifest.json 설정:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.0"
  }
}

태그가 없으면 기본 브랜치의 최신 커밋을 추적합니다:

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

버전을 업데이트할 때 manifest.json의 #tag 접미사를 새 버전 번호로 수정하거나, UPM GUI에서 새 태그 URL을 사용하여 Add package from git URL을 다시 수행하십시오.

사용법

서비스 시작

1. Unity Editor → Window → MCP Server

2. 포트 설정(기본값 8090) 후 Start 클릭

3. 패널의 설정 JSON 복사

에이전트 설정

에이전트의 MCP 설정 파일(예: mcp.json)에 다음 내용을 추가합니다:

{
  "mcpServers": {
    "unity-mcp": {
      "url": "http://localhost:8090/"
    }
  }
}

확장: 사용자 정의 도구 추가

IMcpTool 인터페이스를 구현하고 Editor 어셈블리에 배치하면 서비스 시작 시 자동으로 검색 및 등록됩니다:

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityMcp.Editor;

public class MyCustomTool : IMcpTool
{
    public string Name => "my_custom_tool";
    public string Category => "custom";
    public string Description => "我的自定义工具";
    public string InputSchema => "{\"type\":\"object\",\"properties\":{}}";

    public Task<ToolResult> Execute(Dictionary<string, object> parameters)
    {
        return Task.FromResult(ToolResult.Success("Hello from custom tool!"));
    }
}

요구 사항

• Unity 2022.3+

• Editor 환경 전용, 런타임 빌드에 영향 없음

기여

본 프로젝트 개발 참여를 환영합니다. 자세한 내용은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT