Unreal Engine

Permita que agentes de IA vejam, construam, testem e editem dentro do Unreal Engine 5.7 — incluindo Blueprints, que normalmente são ativos binários opacos.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-unreal

Servidor MCP (Model Context Protocol) que dá a agentes de codificação de IA controle autônomo completo sobre um projeto Unreal Engine 5.7. Binário único em Go, zero dependências externas.

Compile, teste, manipule o editor, edite Blueprints, gere malhas procedurais e consulte a documentação da API UE — tudo por meio de 49 ferramentas MCP que qualquer agente compatível com MCP pode chamar diretamente.

Início 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)

Pré-requisitos

Go 1.25+ — instalar
Unreal Engine 5.7 — para ferramentas de compilação/teste e interação com o editor
Remote Control API plugin — habilitado no UE (veja Habilitando Remote Control API abaixo)
MCPUnreal editor plugin — para ferramentas avançadas do editor (veja plugin/README.md)

Instalação

A partir do Código Fonte

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

Binários Pré-compilados

Baixe de GitHub Releases — disponível para macOS, Linux e Windows em amd64 e arm64.

Habilitando Remote Control API

A Remote Control API é um plugin UE integrado que fornece acesso HTTP a propriedades de atores e chamadas de função na porta 30010. O mcp-unreal a utiliza para as ferramentas get_property, set_property, call_function e move_actor.

Abra seu projeto no Unreal Editor
Vá em Edit > Plugins
Pesquise por "Remote Control API"
Marque a caixa Enabled
Reinicie o editor quando solicitado

Para verificar se está em execução:

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

Você deve obter uma resposta JSON com a versão da API. Se a conexão for recusada, o plugin não está habilitado ou o editor não está em execução.

Instalar o Plugin UE

Copie o diretório plugin/ para a pasta Plugins/ do seu projeto:

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

Recompile o projeto. O plugin inicia um servidor HTTP na porta 8090 quando o editor carrega. Veja plugin/README.md para detalhes.

Configuração por Cliente

O mcp-unreal funciona com qualquer ferramenta de codificação de IA compatível com MCP. Abaixo estão as instruções de configuração para cada uma.

Nota: Substitua /path/to/mcp-unreal pelo caminho real do seu binário compilado (por exemplo, a saída de go install ou make build). Defina MCP_UNREAL_PROJECT para o caminho do arquivo .uproject ou o diretório raiz do projeto.

Claude Code

Registro via CLI:

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

Arquivo de configuração (.mcp.json na raiz do projeto, ou ~/.claude.json para global):

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

Cursor

Arquivo de configuração (.cursor/mcp.json na raiz do projeto, ou ~/.cursor/mcp.json para global):

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

Após salvar, habilite via Cursor Settings > MCP Servers.

OpenAI Codex CLI

Registro via CLI:

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

Arquivo de configuração (.codex/config.toml na raiz do projeto, ou ~/.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"

Aumente tool_timeout_sec para build_project e run_tests, que podem levar mais de 60 segundos.

VS Code with GitHub Copilot

Requer VS Code 1.99+ com o GitHub Copilot Agent Mode habilitado.

Arquivo de configuração (.vscode/mcp.json na raiz do projeto):

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

Windsurf

Arquivo de configuração (~/.codeium/windsurf/mcp_config.json):

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

Cline (VS Code Extension)

Abra o painel do Cline > ícone de MCP Servers > aba Configure > Advanced MCP Settings e adicione:

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

Zed

Arquivo de configuração (~/.config/zed/settings.json):

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

Referência Rápida

Cliente	Arquivo de Configuração	Chave de Nível Superior
Claude Code	`.mcp.json` ou `~/.claude.json`	`mcpServers`
Cursor	`.cursor/mcp.json` ou `~/.cursor/mcp.json`	`mcpServers`
Codex CLI	`.codex/config.toml` ou `~/.codex/config.toml`	`[mcp_servers.<name>]`
VS Code Copilot	`.vscode/mcp.json`	`servers`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Cline	Configurações gerenciadas pela extensão	`mcpServers`
Zed	`~/.config/zed/settings.json`	`context_servers`

Prompt de Sistema Recomendado

Para melhores resultados, adicione o seguinte ao prompt de sistema do seu projeto (por exemplo, CLAUDE.md, .cursorrules, .codex/instructions.md ou equivalente). Isso informa ao agente de IA como usar as ferramentas MCP de forma eficaz.

## 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.

Dica: Para Claude Code, salve isso como CLAUDE.md na raiz do projeto. Para Cursor, salve como .cursorrules. Para Codex, salve como .codex/instructions.md.

Configuração

Variável	Padrão	Descrição
`UE_EDITOR_PATH`	Depende da plataforma	Caminho para o binário `UnrealEditor-Cmd`
`MCP_UNREAL_PROJECT`	Auto-detectado a partir do cwd	Caminho para o arquivo `.uproject` ou raiz do projeto
`RC_API_PORT`	`30010`	Porta HTTP da UE Remote Control API
`PLUGIN_PORT`	`8090`	Porta HTTP do plugin de editor MCPUnreal
`MCP_UNREAL_LOG_LEVEL`	`info`	Nível de log: `debug`, `info`, `warn`, `error`
`MCP_UNREAL_DOCS_INDEX`	`./docs/index.bleve`	Caminho para o índice de documentação bleve

Padrões de 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

Arquitetura

                                                    ┌───────────────────────┐
                                                    │   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       │
                                                    └───────────────────────┘

Três caminhos de comunicação:

Headless — exec.Command invoca UnrealEditor-Cmd para compilações, testes e cooking. Nenhum editor necessário.
Remote Control API — HTTP PUT para localhost:30010 para acesso a propriedades e chamadas de função. Integrado ao UE.
Plugin MCPUnreal — HTTP POST para localhost:8090 para edição de Blueprints, consultas de assets, operações de malha e outros internals profundos do editor.

Veja IMPLEMENTATION.md para o documento completo de arquitetura.

Ferramentas Disponíveis (48)

Build & Compile (Headless)

Ferramenta	Descrição
`build_project`	Compila o projeto UE via UnrealEditor-Cmd / UBT. Retorna JSON estruturado com contagem de erros e detalhes dos erros.
`cook_project`	Faz cook (empacota) conteúdo para uma plataforma alvo usando RunUAT. Suporta cooks iterativos.
`generate_project_files`	Regenera arquivos de projeto da IDE (.xcworkspace / .sln) após adicionar ou remover módulos C++.

Projeto e Configuração (Headless)

Ferramenta	Descrição
`project_ops`	Lê e modifica o arquivo .uproject: obtém informações do projeto, lista/habilita/desabilita plugins, adiciona módulos, define plataformas alvo.
`config_ops`	Lê e escreve arquivos de configuração .ini do projeto UE (DefaultEngine.ini, DefaultGame.ini, etc.): obtém, define, exclui chaves, lista seções.

Automação de Testes (Headless)

Ferramenta	Descrição
`run_tests`	Executa testes de automação headless (-nullrhi) com resultados de aprovação/reprovação por teste e detalhes de falhas.
`run_visual_tests`	Executa testes de automação com renderização GPU habilitada (sem -nullrhi) para testes visuais/renderização.
`list_tests`	Lista nomes de testes de automação disponíveis que correspondem a um padrão de filtro.
`get_test_log`	Lê arquivos de log UE brutos com limites de linha, deslocamentos e filtragem por palavra-chave.

Atores e Propriedades (Editor)

Ferramenta	Descrição
`get_level_actors`	Lista todos os atores no nível atual com classe, caminho, localização, rotação, escala.
`spawn_actor`	Cria um ator pelo nome da classe em uma localização/rotação/escala fornecida.
`delete_actors`	Exclui um ou mais atores por caminho do objeto ou nome de exibição.
`move_actor`	Define localização, rotação e/ou escala de um ator via chamadas de função da RC API (`K2_SetActorLocation`, `K2_SetActorRotation`, `SetActorScale3D`).
`get_property`	Lê um valor de propriedade de um ator via Remote Control API.
`set_property`	Define um valor de propriedade em um ator via Remote Control API.
`call_function`	Chama uma função em um objeto via Remote Control API.

Edição de Blueprints (Editor)

Ferramenta	Descrição
`blueprint_query`	Consulta a estrutura do Blueprint: lista todos os BPs, inspeciona variáveis/funções/gráficos de um BP, obtém nós e conexões do gráfico.
`blueprint_modify`	Modifica Blueprints: cria, adiciona/remove variáveis, adiciona/remove funções, adiciona/exclui nós, conecta/desconecta pinos, define valores de pinos, compila.

Edição de Animation Blueprints (Editor)

Ferramenta	Descrição
`anim_blueprint_query`	Consulta máquinas de estado e estados do AnimBP: lista máquinas de estado, inspeciona estados/transições/blend spaces.
`anim_blueprint_modify`	Modifica AnimBPs: adiciona/remove estados, adiciona/remove transições, define blend spaces, define animações de estado, define regras de transição, adiciona notify states.

Assets (Editor)

Ferramenta	Descrição
`search_assets`	Pesquisa assets por classe, caminho, nome ou tag. Retorna resultados paginados.
`get_asset_info`	Obtém informações detalhadas do asset, incluindo dependências e referenciadores.

Materiais (Editor)

Ferramenta	Descrição
`material_ops`	Operações de material: create, create_instance, set_parameter, set_texture, get_parameters, list_parameters.

Personagens e Input (Editor)

Ferramenta	Descrição
`character_config`	Configuração de personagem: get_config, set_movement, set_capsule, set_mesh, set_camera, get_movement_modes.
`input_ops`	Operações de Enhanced Input: list_actions, list_contexts, add_action, remove_action, add_context, bind_action, unbind_action, get_bindings.

Geração de Conteúdo Procedural (Editor)

Ferramenta	Descrição
`pcg_ops`	Operações de gráfico PCG: list_components, get_graph, execute, set_parameter, add_node, connect_nodes, get_results.

Gameplay Ability System (Editor)

Ferramenta	Descrição
`gas_ops`	Operações GAS: list_abilities, grant_ability, activate, get_attributes, set_attribute, apply_effect, remove_effect, list_active_effects.

Niagara VFX (Editor)

Ferramenta	Descrição
`niagara_ops`	Operações Niagara: spawn_system, set_parameter, get_parameter, activate, deactivate, list_emitters, set_emitter_enabled, get_system_info.

Geração de Malhas (Editor)

Ferramenta	Descrição
`procedural_mesh`	Cria e modifica geometria do ProceduralMeshComponent: create_section, update_section, clear, set_material.
`realtime_mesh`	Cria e modifica geometria do RealtimeMeshComponent (requer plugin RMC): create_lod, create_section_group, create_section, update_mesh_data, set_material_slot, setup_collision.

Níveis (Editor)

Ferramenta	Descrição
`level_ops`	Gerenciamento de níveis: get_current, list_levels, load_level, save_level, new_level, add_sublevel, remove_sublevel, set_streaming_method.

Utilitários do Editor (Editor)

Ferramenta	Descrição
`run_console_command`	Executa um comando de console do Unreal no editor.
`get_output_log`	Lê o log de saída do editor com filtragem opcional por categoria e verbosidade.
`capture_viewport`	Captura uma captura de tela do viewport ativo. Retorna MCP ImageContent (visível pelo LLM) ou salva em arquivo. Defina `include_ui=true` para capturar com overlays Slate/UMG (HUD, menus) — requer PIE.
`execute_script`	Executa um script Python no ambiente Python do editor.
`live_compile`	Dispara a compilação do Live Coding (hot reload) sem reiniciar o editor.
`pie_control`	Controla sessões Play In Editor (PIE): iniciar, parar ou verificar status. Suporta override de mapa e modo Simulate In Editor. Iniciar/parar são assíncronos — use status para verificar.
`player_control`	Controla o pawn do jogador e a câmera do viewport do editor. Operações: `get_info` (estado do jogador), `teleport` (mover pawn), `set_rotation` (definir direção de visão), `set_view_target` (alterar alvo da câmera) — requerem PIE. `get_camera`/`set_camera` movem a câmera do viewport do editor sem PIE.

Componentes e Instanciação (Editor)

Ferramenta	Descrição
`get_actor_components`	Obtenha a hierarquia completa de componentes de um ator, incluindo tipos, visibilidade, referências de malha e transformações.
`ism_ops`	Gerencie componentes ISM/HISM: crie, adicione/remova/atualize instâncias, defina materiais, obtenha contagens de instâncias.

Texturas (Editor)

Ferramenta	Descrição
`texture_ops`	Importe imagens como assets de textura, consulte informações de textura, atribua texturas a parâmetros de material, liste texturas.

DataTables (Editor)

Ferramenta	Descrição
`data_asset_ops`	Gerencie DataTables: liste, leia linhas, adicione/atualize/exclua linhas, crie tabelas, importe de CSV.

Fab Marketplace (Editor)

Ferramenta	Descrição
`fab_ops`	Gerencie o cache de assets do Fab marketplace: liste assets baixados, importe para o projeto, limpe o cache.

Subsistemas e UI (Editor)

Ferramenta	Descrição
`subsystem_query`	Liste subsistemas UE ativos por tipo (world, game_instance, engine, editor, local_player).
`ui_query`	Inspecione a hierarquia de widgets Slate e UMG: árvore, encontre por classe, obtenha detalhes, liste bindings.

Depuração de Rede (Editor)

Ferramenta	Descrição
`network_debug`	Inspecione solicitações HTTP ativas, conexões WebSocket e logs recentes de solicitação/resposta.

Documentação (Sempre Disponível)

Ferramenta	Descrição
`status`	Verifique a saúde do servidor, o caminho de instalação do UE, informações do projeto e conectividade com o editor.
`lookup_docs`	Pesquise documentos da API do UE 5.7, documentos do RealtimeMesh e documentos do projeto por consulta em linguagem natural.
`lookup_class`	Obtenha referência de classe estruturada (herança, propriedades, funções) para uma classe UE específica.

Índice de Documentação

Construa o índice de busca da documentação local:

mcp-unreal --build-index

Isso indexa arquivos markdown de docs/ue5.7/ e docs/realtimemesh/, além do CLAUDE.md do seu projeto. O índice é armazenado em ./docs/index.bleve (configurável via MCP_UNREAL_DOCS_INDEX).

Para adicionar documentação personalizada, coloque arquivos markdown no diretório docs/ e reconstrua o índice. Consulte docs/README.md.

Exemplo de Uso

Depois de registrado, seu agente de IA pode autonomamente:

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

Desenvolvimento

# 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

Testes de Plugin C++

O plugin MCPUnreal inclui testes de automação que rodam dentro do editor UE sem interface. Eles requerem UE 5.7 instalado localmente e não fazem parte do CI — são opcionais para desenvolvimento 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

Isso usa um projeto UE mínimo em test-project/ que faz symlink do código-fonte do plugin e executa todos os testes MCPUnreal.* via UnrealEditor-Cmd -nullrhi.

Contribuindo

Veja CONTRIBUTING.md para configuração de desenvolvimento, padrões de código e como adicionar novas ferramentas.

Licença

Apache-2.0 — veja LICENSE.

Unreal Engine é uma marca registrada da Epic Games, Inc. Este projeto não é afiliado ou endossado pela Epic Games.