MCP(Model Context Protocol)를 사용하여 Unity와 AI 어시스턴트를 연결합니다.
Unity-MCP는 Unity 게임 개발을 위한 모델 컨텍스트 프로토콜(Model Context Protocol)의 오픈 소스 구현입니다. AI 어시스턴트가 표준화된 인터페이스를 통해 Unity 게임 환경과 상호 작용할 수 있도록 지원하여 AI 지원 게임 개발, 자동 테스트, 장면 분석 및 런타임 디버깅을 가능하게 합니다.
AILogger를 사용하여 지속성을 유지하도록 아키텍처가 간소화되어 별도의 서버 구성 요소가 필요 없게 되었습니다.
지엑스피1
AI Assistant : MCP 프로토콜을 사용하여 Unity-MCP STDIO 클라이언트와 통신합니다.
Unity-MCP STDIO 클라이언트 : Unity 클라이언트에 명령을 전달하고 결과를 AILogger에 저장합니다.
Unity 클라이언트 : Unity에서 명령을 실행하고 결과를 반환합니다.
AILogger : 나중에 검색할 수 있도록 로그와 결과를 저장합니다.
Unity-MCP STDIO 클라이언트는 코드 실행과 쿼리 모두에 대한 엔드포인트를 제공하는 Unity 클라이언트와 직접 통신합니다. 쿼리 도구는 쿼리를 return 문으로 래핑하여 코드 실행으로 변환합니다.
Related MCP server: Advanced Unity MCP
Unity 런타임 환경에서 C# 코드 실행
게임 객체와 그 구성 요소를 검사합니다
장면 계층 구조 및 구조 분석
테스트를 실행하고 결과를 받습니다.
게임 객체 및 구성 요소에 대한 메서드 호출
런타임 중 게임 상태 수정
Unity Editor 확장: 게임 실행 주기를 넘어 지속되는 Editor 확장
Docker 컨테이너: 네트워크를 통해 Unity와 통신하는 컨테이너화된 버전
NPX 패키지: NPX를 통해 설치 및 실행할 수 있는 Node.js 패키지
MCP 아키텍처 : MCP 아키텍처 및 네임스페이스 개요
MCP STDIO 클라이언트 : MCP STDIO 클라이언트 및 로깅 기능에 대한 정보
쿼리 도구 : 쿼리 도구와 그 작동 방식에 대한 자세한 정보
AILogger 통합 : AILogger 통합에 대한 자세한 정보
API 참조 : API 엔드포인트에 대한 자세한 정보
설치 가이드 : Unity-MCP 설치 및 설정을 위한 단계별 지침
개발 가이드 : 개발 환경 및 워크플로에 대한 정보
핫 리로딩 가이드 : 개발 환경에서 핫 리로딩에 대한 자세한 정보
핫 리로딩 빠른 참조 : 핫 리로딩 명령 및 팁에 대한 빠른 참조 가이드
기여 가이드 : 프로젝트 기여를 위한 가이드라인
Unity-MCP를 시작하려면 다음 단계를 따르세요.
저장소를 복제합니다.
git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCP종속성 설치:
npm install프로젝트를 빌드하세요:
npm run buildMCP STDIO 클라이언트를 시작합니다.
npm start이렇게 하면 Unity와 통신하고 지속성을 위해 AILogger를 사용하는 MCP STDIO 클라이언트가 시작됩니다.
참고: AILogger가 http://localhost:3030 에서 실행 중인지 확인하거나 AI_LOGGER_URL 환경 변수를 설정하여 AILogger 인스턴스를 가리키도록 하세요.
테스트 실행:
# Run all tests
npm test
# Run only unit tests
npm run test:unit
# Run only e2e tests
npm run test:e2e
# Run tests with a specific pattern
npm test -- --testNamePattern="should return the server manifest"
npm run test:unit -- --testNamePattern="should return the server manifest"
npm run test:e2e -- --testNamePattern="should discover the test server"자세한 지침은 설치 가이드를 참조하세요.
Unity-MCP 브리지를 AI 어시스턴트에 연결하려면 MCP 구성 파일을 만들어야 합니다.
{
"mcpServers": {
"unity-ai-bridge": {
"url": "http://localhost:8080/sse"
}
}
}이 파일을 AI 비서의 적절한 위치에 저장하세요. Claude의 경우, 일반적으로 Claude Desktop 앱의 구성 디렉터리에 저장됩니다.
Unity-MCP 브리지는 다음과 같은 도구를 제공합니다.
execute_code : Unity에서 C# 코드를 직접 실행합니다.
쿼리 : 점 표기법을 사용하여 쿼리를 실행하여 객체, 속성, 메서드에 액세스합니다.
get_logs : AILogger에서 로그를 검색합니다.
get_log_by_name : AILogger에서 특정 로그를 검색합니다.
Unity에서 execute_code 도구를 사용하여 C# 코드를 실행할 수 있습니다. 코드는 Unity 런타임 환경에서 실행되며, 결과는 나중에 검색할 수 있도록 AILogger에 저장됩니다.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "execute_code",
"arguments": {
"code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
"timeout": 5000
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
}
]
}
}query 도구를 사용하여 Unity 객체를 쿼리할 수 있습니다. 이를 통해 점 표기법을 사용하여 객체, 속성 및 메서드에 액세스할 수 있습니다.
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "query",
"arguments": {
"query": "Camera.main.transform.position",
"timeout": 5000
}
}
}{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
}
]
}
}get_log_by_name 도구를 사용하면 AILogger에서 이전 작업의 결과를 검색할 수 있습니다.
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_log_by_name",
"arguments": {
"log_name": "unity-execute-1712534400000",
"limit": 1
}
}
}{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
}
]
}
}AI 어시스턴트가 Unity 도구에 액세스하면 다음과 같은 작업을 수행하도록 요청할 수 있습니다.
Can you execute the following C# code in Unity?
GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);MIT
T 사보( @TSavo )
Lists all the files inside a Unity project.
| Name | Required | Description | Default |
|---|---|---|---|
| projectName | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Lists') but doesn't describe key traits like whether it's read-only (implied but not explicit), what format the output takes (e.g., list of filenames vs. metadata), pagination, error conditions, or permissions required. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized for a simple listing tool and front-loaded with the core action, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is incomplete. It lacks details on parameter semantics, output format, and behavioral context (e.g., read-only nature, error handling). While concise, it doesn't provide enough information for an agent to use the tool effectively without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the parameter 'projectName' is undocumented in the schema. The description adds no information about this parameter—it doesn't explain what 'projectName' refers to (e.g., a Unity project identifier), valid formats, or examples. With low schema coverage, the description fails to compensate, leaving the parameter's meaning unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Lists') and resource ('all the files inside a Unity project'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_projects' (which lists projects) or 'read_file' (which reads file contents), missing the opportunity to clarify its specific scope within the toolset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing project), exclusions, or comparisons to siblings like 'list_projects' for project-level listing or 'read_file' for accessing file details. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all available Unity projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether results are paginated, sorted, filtered, or include metadata; whether it requires authentication; or what the return format looks like. This leaves significant gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose with zero wasted words. It's appropriately sized for a simple list operation with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'lists' entails (e.g., format, metadata included) or behavioral aspects, leaving the agent with insufficient context to understand the tool's full behavior beyond its basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, earning a baseline high score since it doesn't need to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lists') and resource ('all available Unity projects'), making the purpose immediately understandable. It doesn't differentiate from sibling tools like 'list_files_in_project' or 'read_file', which would require mentioning it returns project-level metadata rather than file contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that 'list_files_in_project' is for files within a specific project or 'read_file' is for file contents, leaving the agent to infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the contents of a file inside a Unity project.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Reads') but doesn't mention potential constraints like file size limits, encoding issues, error handling for missing files, or performance implications. This leaves significant gaps in understanding how the tool behaves beyond its basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It front-loads the core action and context efficiently, making it easy to parse and understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (reading file contents), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., text content, binary data, error messages) or address common edge cases like permissions or file existence, making it inadequate for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It implies the 'path' parameter refers to a file path within a Unity project, adding context beyond the schema's minimal type constraints. However, it doesn't specify path format (e.g., relative vs. absolute), supported file types, or examples, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reads') and target ('contents of a file inside a Unity project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_files_in_project' (which enumerates files vs. reading content), leaving room for minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_files_in_project' or 'list_projects'. It mentions the context ('inside a Unity project') but lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0list_files_in_projectlist_projectsread_fileScored across 3 tools
Each tool has a clearly distinct purpose: list_projects enumerates projects, list_files_in_project enumerates files within a project, and read_file retrieves file contents. There is no overlap or ambiguity in their functions, making it easy for an agent to select the correct tool.
All tool names follow a consistent verb_noun pattern (list_projects, list_files_in_project, read_file) with clear, descriptive verbs. The naming is uniform and predictable, enhancing usability and reducing confusion.
With only 3 tools, the set feels thin for a Unity project management server, as it lacks essential operations like creating, updating, or deleting files or projects. While the tools are well-defined, the count is borderline low for the apparent scope.
The tool surface is significantly incomplete for Unity project management. It covers listing and reading but lacks any write, update, or delete operations (e.g., create_project, write_file, delete_file), which are critical for full lifecycle coverage and will likely cause agent failures in many workflows.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Savecraft serves real save game data and expert game knowledge to AI assistants.
