使用模型上下文协议 (MCP) 在 Unity 和 AI 助手之间建立桥梁。
Unity-MCP 是 Unity 游戏开发的模型上下文协议 (MCP) 的开源实现。它使 AI 助手能够通过标准化接口与 Unity 游戏环境进行交互，从而实现 AI 辅助游戏开发、自动化测试、场景分析和运行时调试。
该架构已简化为使用 AILogger 进行持久化，从而无需单独的服务器组件：
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILoggerAI 助手：使用 MCP 协议与 Unity-MCP STDIO 客户端进行通信
Unity-MCP STDIO 客户端：将命令转发到 Unity 客户端并将结果存储在 AILogger 中
Unity Client ：在Unity中执行命令并返回结果
AILogger ：存储日志和结果以供日后检索
Unity-MCP STDIO 客户端直接与 Unity 客户端通信，后者提供代码执行和查询的端点。查询工具通过将查询包装在return语句中，将其转换为代码执行。
Related MCP server: Advanced Unity MCP
在 Unity 运行时环境中执行 C# 代码
检查游戏对象及其组件
分析场景层次和结构
运行测试并接收结果
调用游戏对象和组件的方法
在运行时修改游戏状态
Unity 编辑器扩展：一个在游戏执行周期之外持续存在的编辑器扩展
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 build启动 MCP 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桌面应用程序的配置目录中。
Unity-MCP 桥提供以下工具：
execute_code ：在 Unity 中直接执行 C# 代码。
query ：使用点符号执行查询来访问对象、属性和方法。
get_logs ：从 AILogger 检索日志。
get_log_by_name ：从 AILogger 检索特定日志。
您可以使用execute_code工具在Unity中执行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);麻省理工学院
T Savo（ @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.
