Un puente entre Unity y los asistentes de IA que utilizan el Protocolo de contexto de modelo (MCP).
Unity-MCP es una implementación de código abierto del Protocolo de Contexto de Modelo para el desarrollo de juegos Unity. Permite que los asistentes de IA interactúen con los entornos de juego Unity a través de una interfaz estandarizada, lo que facilita el desarrollo de juegos asistido por IA, las pruebas automatizadas, el análisis de escenas y la depuración en tiempo de ejecución.
Se ha simplificado la arquitectura para utilizar AILogger para la persistencia, eliminando la necesidad de un componente de servidor separado:
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILoggerAsistente de IA : se comunica con el cliente Unity-MCP STDIO mediante el protocolo MCP
Cliente Unity-MCP STDIO : reenvía comandos al cliente Unity y almacena los resultados en AILogger
Cliente de Unity : ejecuta comandos en Unity y devuelve resultados
AILogger : almacena registros y resultados para su posterior recuperación
El cliente STDIO de Unity-MCP se comunica directamente con el cliente de Unity, que proporciona puntos finales tanto para la ejecución de código como para las consultas. La herramienta de consultas transforma las consultas en ejecución de código envolviéndolas en una declaración return .
Related MCP server: Advanced Unity MCP
Ejecutar código C# en el entorno de ejecución de Unity
Inspeccionar los objetos del juego y sus componentes
Analizar jerarquías y estructuras de escenas
Ejecutar pruebas y recibir resultados
Invocar métodos en objetos y componentes del juego
Modificar el estado del juego durante el tiempo de ejecución
Extensión del editor de Unity: una extensión del editor que persiste más allá de los ciclos de ejecución del juego
Contenedor Docker: una versión en contenedor que se comunica con Unity a través de la red
Paquete NPX: un paquete Node.js que se puede instalar y ejecutar a través de NPX
Arquitectura MCP : descripción general de la arquitectura y los espacios de nombres de MCP
Cliente MCP STDIO : información sobre el cliente MCP STDIO y sus capacidades de registro
Herramienta de consulta : información detallada sobre la herramienta de consulta y cómo funciona
Integración con AILogger : información detallada sobre la integración con AILogger
Referencia de API : información detallada sobre los puntos finales de la API
Guía de instalación : instrucciones paso a paso para instalar y configurar Unity-MCP
Guía de desarrollo : información sobre el entorno de desarrollo y el flujo de trabajo
Guía de recarga en caliente : información detallada sobre la recarga en caliente en el entorno de desarrollo
Referencia rápida de recarga en caliente : Guía de referencia rápida para comandos y consejos de recarga en caliente
Guía de contribución : Pautas para contribuir al proyecto
Para comenzar a utilizar Unity-MCP, siga estos pasos:
Clonar el repositorio:
git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCPInstalar dependencias:
npm installConstruir el proyecto:
npm run buildInicie el cliente MCP STDIO:
npm startEsto iniciará el cliente MCP STDIO que se comunica con Unity y utiliza AILogger para la persistencia.
Nota: asegúrese de que AILogger se esté ejecutando en http://localhost:3030 o configure la variable de entorno AI_LOGGER_URL para que apunte a su instancia de AILogger.
Ejecutar pruebas:
# 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"Para obtener instrucciones más detalladas, consulte la Guía de instalación .
Para conectar el puente Unity-MCP a un asistente de IA, debe crear un archivo de configuración MCP:
{
"mcpServers": {
"unity-ai-bridge": {
"url": "http://localhost:8080/sse"
}
}
}Coloque este archivo en la ubicación adecuada para su asistente de IA. En el caso de Claude, normalmente se encuentra en el directorio de configuración de la aplicación Claude Desktop.
El puente Unity-MCP proporciona las siguientes herramientas:
execute_code : ejecuta código C# directamente en Unity.
consulta : ejecuta una consulta utilizando la notación de puntos para acceder a objetos, propiedades y métodos.
get_logs : recupera registros de AILogger.
get_log_by_name : recupera un registro específico de AILogger.
Puedes ejecutar código C# en Unity con la herramienta execute_code . El código se ejecutará en el entorno de ejecución de Unity y el resultado se almacenará en AILogger para su posterior recuperación.
{
"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}}"
}
]
}
}Puedes consultar objetos de Unity con la herramienta query . Esto te permite acceder a objetos, propiedades y métodos mediante notación de puntos.
{
"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}}"
}
]
}
}Puede recuperar los resultados de operaciones anteriores de AILogger utilizando la herramienta get_log_by_name .
{
"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\"}]}"
}
]
}
}Una vez que el asistente de IA tenga acceso a la herramienta Unity, puedes pedirle que realice tareas como:
Can you execute the following C# code in Unity?
GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);Instituto Tecnológico de Massachusetts (MIT)
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.
