Unreal Engine

Permite que los agentes de IA vean, construyan, prueben y editen dentro de Unreal Engine 5.7, incluidos los Blueprints, que normalmente son activos binarios opacos.

GitHub
67
Prueba este MCPPatrocinado

Documentación

mcp-unreal

CI Go 1.25+ License: Apache-2.0

Servidor MCP (Model Context Protocol) que brinda a los agentes de codificación con IA control autónomo completo sobre un proyecto de Unreal Engine 5.7. Un único binario Go, cero dependencias externas.

Compila, prueba, manipula el editor, edita Blueprints, genera mallas procedurales y consulta la documentación de la API de UE — todo a través de 49 herramientas MCP que cualquier agente compatible con MCP puede invocar directamente.

Inicio Rápido

# Install
go install github.com/remiphilippe/mcp-unreal/cmd/mcp-unreal@latest

# Build the documentation index
mcp-unreal --build-index

# Register with your AI coding tool (see Setup section below)

Requisitos Previos

  • Go 1.25+ — instalar
  • Unreal Engine 5.7 — para las herramientas de compilación/pruebas y la interacción con el editor
  • Complemento Remote Control API — habilitado en UE (consulta Habilitar Remote Control API más abajo)
  • Complemento de editor MCPUnreal — para herramientas avanzadas del editor (consulta plugin/README.md)

Instalación

Desde el Código Fuente

git clone https://github.com/remiphilippe/mcp-unreal.git
cd mcp-unreal
make build

Binarios Precompilados

Descarga desde GitHub Releases — disponibles para macOS, Linux y Windows en amd64 y arm64.

Habilitar Remote Control API

La Remote Control API es un complemento integrado de UE que proporciona acceso HTTP a las propiedades de actores y llamadas a funciones en el puerto 30010. mcp-unreal la utiliza para las herramientas get_property, set_property, call_function y move_actor.

  1. Abre tu proyecto en Unreal Editor
  2. Ve a Edit > Plugins
  3. Busca "Remote Control API"
  4. Marca la casilla Enabled
  5. Reinicia el editor cuando se te solicite

Para verificar que está en ejecución:

curl http://localhost:30010/remote/info

Deberías recibir una respuesta JSON con la versión de la API. Si la conexión es rechazada, el complemento no está habilitado o el editor no está en ejecución.

Instalar el Complemento de UE

Copia el directorio plugin/ en la carpeta Plugins/ de tu proyecto:

cp -r plugin/ /path/to/YourProject/Plugins/MCPUnreal/

Reconstruye el proyecto. El complemento inicia un servidor HTTP en el puerto 8090 cuando el editor se carga. Consulta plugin/README.md para más detalles.

Configuración por Cliente

mcp-unreal funciona con cualquier herramienta de codificación con IA compatible con MCP. A continuación se presentan las instrucciones de configuración para cada una.

Nota: Reemplaza /path/to/mcp-unreal con la ruta real a tu binario compilado (por ejemplo, la salida de go install o make build). Establece MCP_UNREAL_PROJECT a la ruta de tu archivo .uproject o al directorio raíz del proyecto.

Claude Code

Registro CLI:

claude mcp add mcp-unreal -- /path/to/mcp-unreal

Archivo de configuración (.mcp.json en la raíz del proyecto, o ~/.claude.json para global):

{
  "mcpServers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Cursor

Archivo de configuración (.cursor/mcp.json en la raíz del proyecto, o ~/.cursor/mcp.json para global):

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Después de guardar, habilítalo mediante Cursor Settings > MCP Servers.

OpenAI Codex CLI

Registro CLI:

codex mcp add mcp-unreal -- /path/to/mcp-unreal

Archivo de configuración (.codex/config.toml en la raíz del proyecto, o ~/.codex/config.toml para global):

[mcp_servers.mcp-unreal]
command = "/path/to/mcp-unreal"
args = []
tool_timeout_sec = 120

[mcp_servers.mcp-unreal.env]
MCP_UNREAL_PROJECT = "/path/to/MyProject/MyProject.uproject"

Aumenta tool_timeout_sec para build_project y run_tests, que pueden tardar más de 60 segundos.

VS Code con GitHub Copilot

Requiere VS Code 1.99+ con GitHub Copilot Agent Mode habilitado.

Archivo de configuración (.vscode/mcp.json en la raíz del proyecto):

{
  "servers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "${workspaceFolder}"
      }
    }
  }
}

Windsurf

Archivo de configuración (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Cline (Extensión de VS Code)

Abre el panel de Cline > ícono de MCP Servers > pestaña Configure > Advanced MCP Settings, y luego agrega:

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Zed

Archivo de configuración (~/.config/zed/settings.json):

{
  "context_servers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Referencia Rápida

ClienteArchivo de ConfiguraciónClave de Nivel Superior
Claude Code.mcp.json o ~/.claude.jsonmcpServers
Cursor.cursor/mcp.json o ~/.cursor/mcp.jsonmcpServers
Codex CLI.codex/config.toml o ~/.codex/config.toml[mcp_servers.<name>]
VS Code Copilot.vscode/mcp.jsonservers
Windsurf~/.codeium/windsurf/mcp_config.jsonmcpServers
ClineConfiguración gestionada por la extensiónmcpServers
Zed~/.config/zed/settings.jsoncontext_servers

Prompt de Sistema Recomendado

Para obtener los mejores resultados, agrega lo siguiente al prompt de sistema de tu proyecto (por ejemplo, CLAUDE.md, .cursorrules, .codex/instructions.md o equivalente). Esto le indica al agente de IA cómo usar las herramientas MCP de manera efectiva.

## Unreal Engine MCP Tools

This project uses mcp-unreal for AI-driven Unreal Engine development. The following MCP tools are available:

### Workflow Guidelines

1. **Always check status first**: Call `status` to verify the editor and plugin connections before attempting editor operations.
2. **Look up docs before writing UE code**: Use `lookup_class` to get class references (inheritance, properties, functions) and `lookup_docs` for API patterns before writing C++ or Blueprint logic.
3. **Build-test cycle**: After editing C++ files, call `build_project` to compile, then `run_tests` to verify. Read build errors carefully — use `lookup_docs` to understand UE APIs.
4. **Actor workflow**: Use `get_level_actors` to discover existing actors, `spawn_actor` to create new ones, `move_actor` to position them, and `set_property`/`get_property` to read/write properties.
5. **Blueprint workflow**: Use `blueprint_query` with operation `list` to find Blueprints, then `list_variables`/`list_functions`/`list_nodes` to inspect them. Use `blueprint_modify` to make changes, and always `compile` after modifications.
6. **Material workflow**: Use `material_ops` with `create` to make new materials, `get_parameters` to inspect existing ones, and `set_parameter` or `set_texture` to modify them.
7. **Save your work**: The editor does not auto-save. After making changes, use `level_ops` with `save_level` or remind the user to save.
8. **PIE testing**: Use `pie_control` with operation `start` to begin a Play In Editor session, `status` to verify it started, and `stop` to end it. Use `capture_viewport` with `include_ui=true` during PIE to see the game view with HUD/menus. Use `player_control` to move the player pawn (`teleport`, `set_rotation`) or reposition the editor viewport camera (`get_camera`, `set_camera`).

### Tool Modes

- **Headless tools** (`build_project`, `run_tests`, `cook_project`, etc.) do NOT require the editor to be running. They invoke UnrealEditor-Cmd directly.
- **Editor tools** (actors, blueprints, materials, etc.) require the Unreal Editor to be open with the MCPUnreal plugin loaded.
- **Documentation tools** (`lookup_docs`, `lookup_class`) are always available — use them liberally.

### Object Paths

Many tools require UE object paths. The format is:
- Actor paths: `/Game/Maps/MapName.MapName:PersistentLevel.ActorName`
- Asset paths: `/Game/Folder/AssetName`
- Engine assets: `/Engine/BasicShapes/Cube`

Use `get_level_actors` to discover actor paths, and `search_assets` to find asset paths.

Consejo: Para Claude Code, guarda esto como CLAUDE.md en la raíz de tu proyecto. Para Cursor, guárdalo como .cursorrules. Para Codex, guárdalo como .codex/instructions.md.

Configuración

VariablePredeterminadoDescripción
UE_EDITOR_PATHDependiente de la plataformaRuta al binario de UnrealEditor-Cmd
MCP_UNREAL_PROJECTDetectado automáticamente desde cwdRuta al archivo .uproject o directorio raíz del proyecto
RC_API_PORT30010Puerto HTTP de la Remote Control API de UE
PLUGIN_PORT8090Puerto HTTP del complemento de editor MCPUnreal
MCP_UNREAL_LOG_LEVELinfoNivel de registro: debug, info, warn, error
MCP_UNREAL_DOCS_INDEX./docs/index.bleveRuta al índice de documentación de bleve

Valores predeterminados por plataforma para UE_EDITOR_PATH:

  • macOS: /Users/Shared/Epic Games/UE_5.7/Engine/Binaries/Mac/UnrealEditor-Cmd
  • Windows: C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe
  • Linux: /opt/UnrealEngine/Engine/Binaries/Linux/UnrealEditor-Cmd

Arquitectura

                                                    ┌───────────────────────┐
                                                    │   UE 5.7 Editor       │
                                                    │                       │
                                                    │  ┌─────────────────┐  │
                                                    │  │ Remote Control  │  │
                                              ┌────►│  │ API (port 30010)│  │
                                              │     │  │ (built-in)      │  │
                                              │     │  └─────────────────┘  │
┌──────────────┐    stdio     ┌──────────────┐│     │                       │
│  AI Coding   │   JSON-RPC   │              ││     │  ┌─────────────────┐  │
│    Agent     │◄────────────►│  mcp-unreal  │├────►│  │ MCPUnreal       │  │
│ (Claude Code │              │ (Go binary)  ││     │  │ Plugin (port    │  │
│  Cursor, etc)│              │              ││     │  │ 8090)           │  │
└──────────────┘              │ 49 tools     │┘     │  │ • Actors        │  │
                              │ doc index    │      │  │ • Blueprints    │  │
                              │              │      │  │ • Materials     │  │
                              │ ┌──────────┐ │      │  │ • PCG / GAS    │  │
                              │ │ Headless │ │      │  │ • Niagara       │  │
                              │ │ exec.Cmd │─┼──────│──│ • Mesh ops      │  │
                              │ └──────────┘ │      │  │ • Levels        │  │
                              │              │      │  └─────────────────┘  │
                              │ ┌──────────┐ │      │                       │
                              │ │ Bleve    │ │      └───────────────────────┘
                              │ │ Doc Index│ │
                              │ └──────────┘ │      ┌───────────────────────┐
                              │              │──────│ docs/                 │
                              └──────────────┘      │ ├── ue5.7/            │
                                                    │ ├── realtimemesh/     │
                                                    │ └── index.bleve       │
                                                    └───────────────────────┘

Tres rutas de comunicación:

  1. Headless — exec.Command invoca UnrealEditor-Cmd para compilaciones, pruebas y cooking. No se necesita editor.
  2. Remote Control API — HTTP PUT a localhost:30010 para acceso a propiedades y llamadas a funciones. Integrada en UE.
  3. Complemento MCPUnreal — HTTP POST a localhost:8090 para edición de Blueprints, consultas de activos, operaciones de mallas y otros aspectos internos profundos del editor.

Consulta IMPLEMENTATION.md para el documento completo de arquitectura.

Herramientas Disponibles (48)

Compilación y Compilado (Headless)

HerramientaDescripción
build_projectCompila el proyecto de UE mediante UnrealEditor-Cmd / UBT. Devuelve JSON estructurado con el recuento de errores y los detalles de los errores.
cook_projectCocina (empaqueta) contenido para una plataforma de destino usando RunUAT. Admite cocinados iterativos.
generate_project_filesRegenera los archivos de proyecto del IDE (.xcworkspace / .sln) después de agregar o eliminar módulos de C++.

Proyecto y Configuración (Headless)

HerramientaDescripción
project_opsLee y modifica el archivo .uproject: obtén información del proyecto, lista/habilita/deshabilita complementos, agrega módulos, establece plataformas de destino.
config_opsLee y escribe archivos de configuración .ini del proyecto de UE (DefaultEngine.ini, DefaultGame.ini, etc.): obtén, establece, elimina claves, lista secciones.

Automatización de Pruebas (Headless)

HerramientaDescripción
run_testsEjecuta pruebas de automatización headless (-nullrhi) con resultados de aprobado/fallido por prueba y detalles de fallos.
run_visual_testsEjecuta pruebas de automatización con renderizado por GPU habilitado (sin -nullrhi) para pruebas visuales/de renderizado.
list_testsLista los nombres de pruebas de automatización disponibles que coinciden con un patrón de filtro.
get_test_logLee archivos de registro sin procesar de UE con límites de líneas, desplazamientos y filtrado por palabras clave.

Actores y Propiedades (Editor)

HerramientaDescripción
get_level_actorsLista todos los actores en el nivel actual con clase, ruta, ubicación, rotación, escala.
spawn_actorGenera un actor por nombre de clase en una ubicación/rotación/escala determinada.
delete_actorsElimina uno o más actores por ruta de objeto o nombre visible.
move_actorEstablece ubicación, rotación y/o escala de un actor mediante llamadas a funciones de la API RC (K2_SetActorLocation, K2_SetActorRotation, SetActorScale3D).
get_propertyLee un valor de propiedad de un actor mediante la Remote Control API.
set_propertyEstablece un valor de propiedad en un actor mediante la Remote Control API.
call_functionLlama a una función en un objeto mediante la Remote Control API.

Edición de Blueprints (Editor)

HerramientaDescripción
blueprint_queryConsulta la estructura de Blueprints: lista todos los BPs, inspecciona las variables/funciones/grafos de un BP, obtén nodos y conexiones del grafo.
blueprint_modifyModifica Blueprints: crea, agrega/elimina variables, agrega/elimina funciones, agrega/elimina nodos, conecta/desconecta pines, establece valores de pines, compila.

Edición de Blueprints de Animación (Editor)

HerramientaDescripción
anim_blueprint_queryConsulta máquinas de estados y estados de AnimBP: lista máquinas de estados, inspecciona estados/transiciones/espacios de mezcla.
anim_blueprint_modifyModifica AnimBPs: agrega/elimina estados, agrega/elimina transiciones, establece espacios de mezcla, establece animaciones de estados, establece reglas de transición, agrega estados de notificación.

Activos (Editor)

HerramientaDescripción
search_assetsBusca activos por clase, ruta, nombre o etiqueta. Devuelve resultados paginados.
get_asset_infoObtén información detallada del activo, incluyendo dependencias y referenciadores.

Materiales (Editor)

HerramientaDescripción
material_opsOperaciones de materiales: create, create_instance, set_parameter, set_texture, get_parameters, list_parameters.

Personajes y Entrada (Editor)

HerramientaDescripción
character_configConfiguración de personajes: get_config, set_movement, set_capsule, set_mesh, set_camera, get_movement_modes.
input_opsOperaciones de Enhanced Input: list_actions, list_contexts, add_action, remove_action, add_context, bind_action, unbind_action, get_bindings.

Generación de Contenido Procedural (Editor)

HerramientaDescripción
pcg_opsOperaciones de grafos PCG: list_components, get_graph, execute, set_parameter, add_node, connect_nodes, get_results.

Sistema de Habilidades de Gameplay (Editor)

HerramientaDescripción
gas_opsOperaciones de GAS: list_abilities, grant_ability, activate, get_attributes, set_attribute, apply_effect, remove_effect, list_active_effects.

Niagara VFX (Editor)

HerramientaDescripción
niagara_opsOperaciones de Niagara: spawn_system, set_parameter, get_parameter, activate, deactivate, list_emitters, set_emitter_enabled, get_system_info.

Generación de Mallas (Editor)

HerramientaDescripción
procedural_meshCrea y modifica geometría de ProceduralMeshComponent: create_section, update_section, clear, set_material.
realtime_meshCrea y modifica geometría de RealtimeMeshComponent (requiere el complemento RMC): create_lod, create_section_group, create_section, update_mesh_data, set_material_slot, setup_collision.

Niveles (Editor)

HerramientaDescripción
level_opsGestión de niveles: get_current, list_levels, load_level, save_level, new_level, add_sublevel, remove_sublevel, set_streaming_method.

Utilidades del Editor (Editor)

HerramientaDescripción
run_console_commandEjecuta un comando de consola de Unreal en el editor.
get_output_logLee el registro de salida del editor con filtrado opcional por categoría y verbosidad.
capture_viewportCaptura una captura de pantalla del viewport activo. Devuelve MCP ImageContent (visible por el LLM) o la guarda en un archivo. Establece include_ui=true para capturar con superposiciones de Slate/UMG (HUD, menús) — requiere PIE.
execute_scriptEjecuta un script de Python en el entorno de Python del editor.
live_compileActiva la compilación de Live Coding (recarga en caliente) sin reiniciar el editor.
pie_controlControla sesiones de Play In Editor (PIE): iniciar, detener o verificar el estado. Admite anulación de mapa y modo Simulate In Editor. Iniciar/detener son asíncronos — usa status para verificar.
player_controlControla el pawn del jugador y la cámara del viewport del editor. Operaciones: get_info (estado del jugador), teleport (mover pawn), set_rotation (establecer dirección de vista), set_view_target (cambiar objetivo de cámara) — requieren PIE. get_camera/set_camera mueven la cámara del viewport del editor sin PIE.

Componentes e Instanciación (Editor)

HerramientaDescripción
get_actor_componentsObtén la jerarquía completa de componentes de un actor, incluyendo tipos, visibilidad, referencias de malla y transformaciones.
ism_opsGestiona componentes ISM/HISM: crear, añadir/eliminar/actualizar instancias, establecer materiales, obtener recuentos de instancias.

Texturas (Editor)

HerramientaDescripción
texture_opsImporta imágenes como activos de textura, consulta información de texturas, asigna texturas a parámetros de material, lista texturas.

DataTables (Editor)

HerramientaDescripción
data_asset_opsGestiona DataTables: listar, leer filas, añadir/actualizar/eliminar filas, crear tablas, importar desde CSV.

Fab Marketplace (Editor)

HerramientaDescripción
fab_opsGestiona la caché de activos de Fab Marketplace: listar activos descargados, importar al proyecto, limpiar caché.

Subsistemas y UI (Editor)

HerramientaDescripción
subsystem_queryLista los subsistemas UE activos por tipo (world, game_instance, engine, editor, local_player).
ui_queryInspecciona la jerarquía de widgets de Slate y UMG: árbol, buscar por clase, obtener detalles, listar enlaces.

Depuración de red (Editor)

HerramientaDescripción
network_debugInspecciona solicitudes HTTP activas, conexiones WebSocket y registros recientes de solicitud/respuesta.

Documentación (Siempre disponible)

HerramientaDescripción
statusComprueba el estado del servidor, la ruta de instalación de UE, la información del proyecto y la conectividad del editor.
lookup_docsBusca en la documentación de la API de UE 5.7, en la documentación de RealtimeMesh y en la documentación del proyecto mediante consultas en lenguaje natural.
lookup_classObtén una referencia de clase estructurada (herencia, propiedades, funciones) para una clase UE específica.

Índice de documentación

Construye el índice de búsqueda de documentación local:

mcp-unreal --build-index

Esto indexa archivos markdown de docs/ue5.7/ y docs/realtimemesh/, además del CLAUDE.md de tu proyecto. El índice se almacena en ./docs/index.bleve (configurable mediante MCP_UNREAL_DOCS_INDEX).

Para añadir documentación personalizada, coloca archivos markdown en el directorio docs/ y reconstruye el índice. Consulta docs/README.md.

Ejemplo de uso

Una vez registrado, tu agente de IA puede de forma autónoma:

You: "Build the project, fix any errors, and run the tests"

Agent calls:
  1. status()                    → editor + plugin online
  2. build_project()             → finds 2 compile errors
  3. lookup_class("AActor")      → looks up the correct API
  4. (edits the C++ source)
  5. build_project()             → clean build
  6. run_tests(filter: "Game")   → 14/14 tests pass

You: "Add a Niagara fire effect to the torch actor"

Agent calls:
  1. get_level_actors(name_filter: "Torch")  → finds actor path
  2. lookup_class("UNiagaraComponent")       → checks API
  3. niagara_ops(operation: "spawn_system", system_path: "/Game/FX/NS_Fire", ...)
  4. niagara_ops(operation: "set_parameter", parameter_name: "SpawnRate", value: 50)

You: "Create a PCG scatter for placing rocks on the landscape"

Agent calls:
  1. lookup_docs("PCG scatter landscape")    → reads PCG docs
  2. pcg_ops(operation: "list_components")   → finds existing PCG actors
  3. spawn_actor(class: "Actor", name: "RockScatter")
  4. pcg_ops(operation: "add_node", node_type: "SurfaceSampler")
  5. pcg_ops(operation: "execute")           → generates rocks

Desarrollo

# Build
make build

# Run all tests with race detector
make test

# Go lint
make lint

# C++ format check (requires clang-format)
make cpp-fmt-check

# Run all checks (Go format, C++ format, vet, lint, tests)
make check

Pruebas del plugin C++

El plugin MCPUnreal incluye pruebas de automatización que se ejecutan sin interfaz dentro del editor de UE. Estas requieren UE 5.7 instalado localmente y no forman parte de CI; son opcionales para el desarrollo local.

# Build the test project (first run ~2-5 min, incremental after)
make test-cpp-build

# Build and run all MCPUnreal.* automation tests
make test-cpp

Esto utiliza un proyecto UE mínimo en test-project/ que enlaza simbólicamente el código fuente del plugin y ejecuta todas las pruebas MCPUnreal.* mediante UnrealEditor-Cmd -nullrhi.

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo, los estándares de codificación y cómo añadir nuevas herramientas.

Licencia

Apache-2.0 — consulta LICENSE.

Unreal Engine es una marca comercial de Epic Games, Inc. Este proyecto no está afiliado ni respaldado por Epic Games.