Unreal Engine MCP

Controle o Unreal Engine com IA. Um servidor MCP que dá aos assistentes de IA (como Claude e Cursor) acesso direto e programático ao ambiente do Unreal Engine para manipular cenas, criar objetos e executar comandos.

GitHub
30
Experimente este MCPPatrocinado

Documentação

unreal-mcp

Unreal MCP Hero Demo

Um servidor MCP que permite que agentes de IA (Claude, Cursor) controlem e manipulem diretamente o Unreal Engine.

Este servidor permite que o Claude (ou qualquer cliente MCP) leia e edite Blueprints do Unreal Engine 5.6/5.8 diretamente, sem gastar sua janela de contexto com JSON bruto do motor, e sem precisar de nada além de uma instalação padrão do Epic Games Launcher.

Architecture

O problema que isso resolve

Se você já tentou apontar um assistente de IA para um projeto Unreal real, você já esbarrou nisto: Blueprints não cabem em uma janela de contexto. Um único grafo despejado como dados brutos do motor é enorme, então ou o modelo nunca vê o projeto o suficiente para ter contexto real, ou você gasta a maior parte do seu orçamento reexplicando o que já existe toda vez que abre uma nova conversa.

Este projeto é construído em torno de uma ideia: o modelo nunca deve receber um despejo bruto do motor. Cada salto entre o Unreal Editor e o Claude compacta os dados: leituras em camadas, edições baseadas em diff e um índice persistente que é construído uma vez e atualizado incrementalmente em vez de ser reescaneado a cada pergunta.

Como funciona

Duas partes:

  • UnrealMCPBridge é um plugin de editor em C++ que roda dentro do UnrealEditor.exe e expõe uma interface TCP local sobre as APIs Kismet2/EdGraph/AssetRegistry do próprio motor. Construído contra uma instalação padrão do launcher: nenhum código-fonte do motor é necessário para compilar ou executar.
  • mcp-server é um servidor MCP em Node/TypeScript que traduz chamadas de ferramentas MCP em solicitações de ponte, e é responsável por manter cada resposta barata: nomes de campos compactos, tamanhos de resultado limitados e sem re-serializar dados verbosos do motor literalmente.

Veja ARCHITECTURE.md para o design completo.

O que há de diferente neste

Já existem vários projetos MCP para Unreal no GitHub, e a partir do UE 5.8 a Epic envia seu próprio plugin MCP experimental de primeira parte (somente 5.8, opt-in, requer habilitar manualmente um "Editor Toolset"). Vale ser direto sobre onde este projeto realmente difere, em vez de apenas afirmar "melhor":

  • Construído em torno da leitura, não apenas da escrita. A maioria dos projetos existentes é forte em criar e manipular Blueprints a partir de um prompt, mas não aborda o que acontece quando o modelo precisa entender um projeto grande e já construído primeiro. A leitura é o cidadão de primeira classe aqui: resumos em camadas antes do detalhe completo, IDs de nós que você pode referenciar sem buscar novamente.
  • Um índice de projeto persistente e atualizado incrementalmente. A ponte indexa Blueprints, funções, variáveis e referências entre ativos uma vez, armazena em cache no disco e atualiza a partir dos delegados do AssetRegistry conforme você edita, em vez de reescaneear o projeto a cada consulta. find_references responde "o que realmente usa este Blueprint" sem que o modelo tenha que enumerar o projeto por conta própria.
  • Um gancho opcional de modelo local para indexação. Se você apontar o UNREAL_MCP_LOCAL_LLM_URL para um modelo local (Ollama ou qualquer coisa compatível com OpenAI), os resumos de indexação são gerados lá em vez de gastar tokens do Claude em trabalho mecânico de varredura. Totalmente opcional. O índice funciona sem isso.
  • Visa tanto 5.6 quanto 5.8 a partir de um único código-base, onde vários projetos existentes estão presos a uma única versão do motor.

Pesquisa completa do ecossistema existente (licenças, arquiteturas, o que cada um faz bem) está em docs/COMPETITIVE_LANDSCAPE.md.

Status

Isto está sendo construído e verificado publicamente, marco a marco. O documento de status de cada marco é escrito honestamente, incluindo o que está compilado/testado versus o que ainda não foi verificado:

Todos os quatro marcos são verificados por compilação, verificados por protocolo, e verificados ao vivo em ambas as versões do motor. Veja docs/LIVE_VERIFICATION.md para a sessão 5.8 contra um projeto real de ~20 Blueprints e docs/UE56_STATUS.md para a do 5.6: leituras retornando dados reais corretos, um ciclo completo de escrita criar/conectar/compilar/salvar, e confirmação de que o índice incremental do projeto realmente permanece atualizado sem reiniciar o editor (a afirmação central do M3).

Ambas as sessões ao vivo valeram a pena ao capturar um bug real que nenhuma quantidade de compilação ou teste de protocolo teria revelado. No 5.8 foi o add_node duplicando um nó de evento de substituição já presente. No 5.6 foi o .uplugin fixando rigidamente o EngineVersion ao 5.8.0: todas as verificações de compilação passaram porque o UnrealBuildTool ignora esse campo, mas o carregador de plugin em tempo de execução o honra, então o editor parou em um diálogo modal de incompatibilidade e a ponte nunca iniciou.

Desde então, tudo isso também foi exercitado ao vivo: remove_node e VariableGet são cobertos pelas suítes de ID de nó e fluxo de controle, e add_node agora coloca Branch, Sequence, Cast e macros da biblioteca padrão (ForEachLoop, WhileLoop, ...) diretamente, verificado construindo e compilando um gráfico condicional real apenas através da ponte. IDs de nós são GUIDs persistentes, e cada escrita é desfeita com Ctrl+Z sob uma transação nomeada "MCP:". Ainda pendente: tipos de nó CustomEvent/VariableSet não tiveram uma verificação ao vivo dedicada, e o catálogo M5 cobre nós com suporte a UFunction; tipos nativos UK2Node são colocados via valores dedicados de nodeType em vez de descobertos através de unreal_find_node.

Início rápido (Instalação em 3 Passos)

Garanta que você tenha Node.js 18+ e um projeto UE 5.6 / 5.8.

1. Instale o Plugin Unreal

Caminho mais fácil: baixe o plugin pré-compilado para a sua versão do motor e descompacte-o na pasta Plugins/UnrealMCPBridge/ do seu projeto, para que você nunca o compile por conta própria:

Ou compile você mesmo copiando a pasta do plugin UnrealMCPBridge para o diretório Plugins/ do seu projeto Unreal:

# macOS / Linux
mkdir -p "/path/to/YourProject/Plugins" && cp -r UnrealMCPBridge "/path/to/YourProject/Plugins/"

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "C:\path\to\YourProject\Plugins"; Copy-Item -Recurse UnrealMCPBridge "C:\path\to\YourProject\Plugins\"

Nota: Recompile/abra seu projeto Unreal para compilar o plugin e garanta que ele esteja habilitado no editor.

2. Compile o Servidor MCP

Instale as dependências do node e compile o código TypeScript:

cd mcp-server && npm install && npm run build

3. Registre o Servidor

Conecte o servidor ao seu cliente MCP usando o caminho absoluto para mcp-server/dist/index.js:

Claude Code:

claude mcp add unreal -- node "/path/to/unreal-mcp/mcp-server/dist/index.js"

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unreal-mcp/mcp-server/dist/index.js"]
    }
  }
}

Uma vez registrado, abra seu projeto no Unreal Editor e verifique a conexão via unreal_ping.

Para mais opções de configuração e detalhes, veja mcp-server/README.md.

Contribuindo

Issues e PRs são bem-vindos. Este projeto é jovem e está se movendo rápido, então verifique os documentos de status acima antes de assumir que algo funciona de ponta a ponta.

Licença

MIT. Veja LICENSE.