Unreal Engine MCP

unreal-mcp

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.

O problema que isso resolve

Se você já tentou apontar um assistente de IA para um projeto Unreal real, você 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 suficiente do projeto 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 para a 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 ele pode fazer

101 ferramentas, agrupadas pela tarefa em vez da API que chamam. Cada uma é exercitada contra um projeto real de ~1.000 Blueprints, não um fixture.

Entender um projeto que você não escreveu get_project_overview, search_project, find_references, map_system, explain_graph, list_blueprints, read_blueprint_summary, read_node_detail, describe_class, find_source, trace_variable, trace_function_calls, list_actors, read_class_defaults, undo_history. Peça "a contagem regressiva" e receba o sistema de volta — os Blueprints, as funções, o que chama o quê, ordenados para leitura — em vez de uma lista de correspondências de strings.

Encontrar bugs, em português claro audit_project, review_blueprint, project_health, find_orphans, check_data_tables, read_runtime_errors, doctor. A auditoria precifica cada descoberta, então o que aparece primeiro é o que realmente custa para você: um Parent: BeginPlay ausente, uma variável replicada cujo OnRep_ está vazio, uma linha de Data Table apontando para um asset deletado, um event graph que nada alcança.

Construir recursos e provar que funcionam plan_feature, scaffold_blueprint, scaffold_widget, build_graph, add_node, connect_pins, add_event_handler, create_function, add_variable, set_variable_replication, auto_layout_graph, cleanup_blueprint, compile_blueprint, verify_feature. Os grafos saem organizados e comentados, porque saída que compila e saída que alguém fica feliz em herdar são coisas diferentes.

Seja qual for a matéria-prima do trabalho Blueprints, C++ (find_source, compile_cpp, hot_reload_cpp), Data Tables, Data Assets, structs, enums, materiais e instâncias, widgets UMG, mapeamentos de input, níveis e atores, Animation Blueprints, Behavior Trees, Niagara. O suporte a leitura é deliberadamente mais amplo que o suporte a escrita, e o README diz qual é qual para cada um.

Vê-lo realmente rodando start_pie, watch_runtime, pie_status, screenshot, run_console_command, stop_pie. Cada outra leitura aqui diz o que um Blueprint afirma que faz. Estas dizem o que ele fez — incluindo a única classe de bug que uma única pessoa não consegue reproduzir sozinha:

Authority: 0 -> 490  changed=true
Client0:   0 -> 0    changed=false      <- the variable is not replicated

Adicionado no último dia

115 commits. As partes que valem a pena conhecer:

• watch_runtime - observar um jogo em execução. Amostra variáveis em atores vivos durante o play, em cada mundo PIE, rotuladas por papel de rede. Comprovado plantando um bug de replicação em um projeto real, observando apenas a cópia do servidor se mover, corrigindo-o e observando ambas se moverem.
• hot_reload_cpp - o Ctrl+Alt+F11 que um humano pressiona. Até agora, um modelo podia encontrar um bug nativo, escrever a correção e provar que compilava — e a mudança ficava no disco, porque o editor em execução segura a DLL. Aplicá-la significava você fechar o editor. Agora é uma única chamada.
• run_console_command - a tecla til. ce StartWave para disparar um evento que nada chama ainda, Ke * ResetHealth para chamar uma função em cada instância, stat unit, slomo, cvars, cheats. Uma definição em vez de quarenta, e ele reporta recognised: false para um erro de digitação em vez de deixar um comando escrito errado parecer um comando funcional que não fez nada.
• Leituras ficaram mais baratas de novo, medido. Contra o mesmo grafo de 809 nós: explain_graph 3.671 -> 2.329, get_project_overview 1.698 -> 829, e find_references e list_blueprints também compactados. Todo o ciclo de encontrar-planta-corrigir-provar é 9 chamadas e ~1.544 tokens, que npm run trial:diagnose executa contra um editor ao vivo em vez de afirmar. Duas outras compactações foram medidas e revertidas — uma economizou 38 tokens e quebrou como você identifica naturalmente um ator.
• Detecção de grafo morto. Um ponto fixo de vivacidade sobre todo o projeto, tendencioso para chamar coisas de vivas: 52 de 511 grafos que nada alcança, no projeto em que foi validado. map_system e plan_feature agora dizem em voz alta que um sistema correspondente à sua busca pode ser o substituído, porque estender algo que nada chama produz um recurso que não pode rodar.
• Novas leituras: Animation Blueprints, Behavior Trees, Niagara, Data Assets. "Os inimigos não estão seguindo" e "o efeito não toca" são frases reais que as pessoas dizem, e nenhuma delas tinha onde aterrissar.
• Uma classe de falha nomeada e caçada. Uma verificação reportando "não encontrei problemas" e "não consegui olhar" com a mesma palavra. Quatro instâncias corrigidas — o médico alegando tudo limpo em um plugin que estava sem dois comandos, find_orphans dizendo "limpo" quando o nome da classe não correspondia a nada, check_data_tables dizendo "limpo" quando uma coluna estava vazia em todas as linhas, e um preset sem a única ferramenta da qual seu próprio trabalho parte.
• Os testes foram testados por mutação. 444 testes, todos com asserções — mas ter asserções não é poder falhar. Doze mutações deliberadas; onze pegas, uma não. Essa uma levou a um defeito real: um nome de verificação que deriva ou nunca foi precificado silenciosamente pontua 1 e afunda sob cada descoberta cosmética.
• Um recurso construído e depois deletado. Um nó SpawnActor que as próprias instruções da ferramenta alegavam há meses. Ele crashou o editor quatro vezes; a coisa toda foi revertida e o README agora diz claramente que não é construível dessa forma. Uma alegação que não é verdade é pior que um recurso ausente.

O que há de diferente neste

Já existem vários projetos MCP para Unreal no GitHub, e a partir da UE 5.8 a Epic envia seu próprio plugin MCP experimental de primeira parte (apenas 5.8, opt-in). Vale ser direto sobre onde este projeto realmente difere, em vez de apenas alegar "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 é a cidadã de primeira classe aqui: resumos em camadas antes do detalhe completo, IDs de nós que você pode referenciar sem buscar de novo.

• Um índice de projeto persistente e atualizado incrementalmente. A ponte indexa Blueprints, funções, variáveis e referências entre assets uma vez, armazena em cache no disco e atualiza a partir dos delegados 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 sozinho.

• Leituras que cabem em uma janela de contexto. Ler um grafo de Blueprint real — 807 nós — costumava retornar 126.477 tokens, 63% de uma janela de 200k em uma única chamada, de um projeto cuja premissa inteira é que o modelo nunca vê um despejo bruto do motor. Agora são 3.110, com o grafo completo a um parâmetro de distância e um filtro match que responde a uma pergunta específica por uma fração disso. Cada leitura é medida contra um projeto real por npm run measure:reads, que encontra o pior grafo sozinho e falha o build se qualquer leitura crescer além do teto.

• Uma superfície de ferramentas que custa 2,4k tokens em vez de 34,8k. Definições de ferramentas são pagas em cada solicitação, antes que sua mensagem seja lida. O perfil search levanta quatro ferramentas e desliga as outras 97 — e porque elas são desligadas em vez de escondidas atrás de um despachante genérico, unreal_enable_tools devolve seus esquemas reais e totalmente tipados. Uma chamada extra no início de uma sessão, nada é sacrificado, e 32k tokens por turno são economizados pelo resto dela. Os números são medidos por npm run check:profiles, que falha o build se um perfil crescer além do orçamento.

• Grafos lidos e escritos como código. explain_graph com format: "dsl" retorna um grafo como expressões-S — if/else reais, os argumentos literais de cada chamada, continuações nomeadas para casts e nós latentes — e build_graph recebe o mesmo texto de volta através de seu parâmetro dsl. Mudar um Blueprint se torna "leia, edite duas linhas, envie de volta" em vez de descobrir quais IDs de nós religar. Um grafo de ramificação de cinco nós tem 2.045 caracteres como estrutura de nó-e-pino e 302 como DSL:

  (event EventBeginPlay
    (bind v1 (cast BP_Door :Object (GetOwner))
      (:then
        (if bIsLocked
          (call PrintString :InString "locked" :Duration 2.0)
          (else
            (set bIsLocked true))))
      (:CastFailed
        (call PrintString :InString "not a door"))))
  

  A forma é tirada do próprio blueprint_dsl.py da Epic no plugin de primeira parte 5.8 — veja docs/EPIC_58_TEARDOWN.md — mas o vocabulário é deste servidor, então o texto faz ida e volta através do nosso próprio escritor em vez do registro de ferramentas deles.

• O servidor diz ao modelo como trabalhar antes de começar. O campo instructions do MCP carrega a ordem de chamada e as strings exatas que nenhum modelo consegue lembrar de forma confiável — o pino alvo é self, as saídas de Sequence são then_0/then_1 — então o modelo chega sabendo delas em vez de gastar chamadas falhas descobrindo-as. unreal_guide então permite que ele procure qualquer outra coisa no meio da tarefa, uma seção por vez.

• Ele pode ver o jogo rodando, não apenas ler os arquivos. watch_runtime amostra variáveis em atores vivos durante o play, em cada mundo PIE, rotuladas por papel de rede. Bugs de replicação são a única classe de defeito que uma única pessoa não consegue reproduzir sozinha — Authority: 0 -> 490, Client0: 0 -> 0 é esse bug observado em vez de argumentado. Nenhum outro projeto no levantamento lê estado de runtime de forma alguma.

• Ele pode terminar uma mudança em C++, não apenas verificar uma. compile_cpp prova que uma edição compila; hot_reload_cpp aplica o patch no editor que já está aberto, que é o Ctrl+Alt+F11 que um humano pressiona. Sem isso, toda correção nativa termina com um humano fechando o editor.

• Descobertas são precificadas, então a importante vem primeiro. A auditoria pontua cada descoberta pelo que ela realmente custa para você, e cada nome de verificação é protegido por um teste — um nome não precificado silenciosamente pontuava 1 e afundava abaixo de todo resultado cosmético, o que foi encontrado por teste de mutação da suíte em vez de lê-la.

• Vereditos distinguem "nada está errado" de "não consegui olhar". Eles costumavam compartilhar uma palavra, em quatro lugares. Uma ferramenta que diz clean quando não conseguiu verificar é pior que uma que não diz nada.

• Atende tanto 5.6 quanto 5.8 a partir de uma única base de código, onde vários projetos existentes estão presos a uma única versão do motor. Modelos locais pequenos ainda são suportados e ainda são medidos — o perfil minimal existe porque um 14B em uma placa de 12 GB carrega com contexto de 8k e falha em 16k — mas agora eles são uma opção explícita, em vez do que o caminho de instalação silenciosamente entrega a todos. Há também um hook opcional de modelo local para indexação (UNREAL_MCP_LOCAL_LLM_URL), que gera resumos de busca fora do seu orçamento de contexto. Totalmente opcional; o índice funciona sem ele.

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

Há também um documento complementar que começa pelo outro lado: docs/COMPLAINTS_SOLVED.md coleta as reclamações que as pessoas realmente registram sobre servidores MCP do Unreal, cada uma com seu link de origem, e afirma claramente se este projeto resolve, resolve parcialmente ou não resolve. As linhas em aberto são deixadas em aberto de propósito.

Status

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

• Marco 1: introspecção de Blueprint somente leitura: compila e roda em uma instalação real do UE 5.8; protocolo MCP verificado de ponta a ponta.
• Marco 2: criar/editar gráficos de Blueprint: criar Blueprints, adicionar nós, conectar pinos, adicionar variáveis, compilar com relatórios de erro estruturados.
• Marco 3: índice de projeto persistente, busca, referências: índice atualizado incrementalmente (com suporte do AssetRegistry, cache em disco), search_project, find_references, get_project_overview, enriquecimento opcional com modelo local para resultados de busca.
• Marco 4: suporte ao UE 5.6: verificado ao vivo em 5.6, 21 de 21 verificações passando, e lançado. O código-fonte do plugin não precisa de nenhuma alteração entre as duas versões do motor.
• Marco 5: catálogo de referência de nós/funções: unreal_find_node e unreal_get_node_signature, lendo a superfície real chamável por Blueprint do motor em execução via reflexão (12.402 funções em 5.6, 15.775 em 5.8, construídas em ~0,1s). unreal_add_node agora responde a um nome de função errado com didYouMean quase-acertos em vez de um beco sem saída.

Todos os quatro marcos são verificados em build, verificados em 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 sessão 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. Em 5.8, foi o add_node duplicando um nó de evento de substituição já presente. Em 5.6, foi o .uplugin fixando rigidamente EngineVersion a 5.8.0: todas as verificações de build 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. Os ids de nó são GUIDs persistentes, e cada escrita é desfeita com Ctrl+Z sob uma transação nomeada "MCP:". Ainda pendente: os tipos de nó CustomEvent/VariableSet não tiveram uma verificação ao vivo dedicada, e o catálogo M5 cobre nós com suporte UFunction; tipos nativos UK2Node são colocados via valores dedicados nodeType em vez de descobertos através de unreal_find_node.

Início Rápido (Instalação em 4 Etapas)

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

1. Instale o Plugin do Unreal

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

Há lançamentos de plugin pré-compilados na página de releases, e eles são mais antigos que este servidor. A ponte ganhou mais de vinte comandos desde o último, e o número do protocolo não mudou, então um plugin antigo parece saudável e depois falha na primeira ferramenta que precisa de um comando que ele não tem. --doctor agora verifica especificamente esses comandos e avisa. Compilar a partir deste checkout é o caminho confiável.

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. Verifique se funciona antes de conectar qualquer coisa

Com o editor aberto, execute:

node mcp-server/dist/index.js --doctor

Ele informa se o plugin está acessível, se o protocolo corresponde ao servidor, se o índice do projeto está construído ou ainda escaneando, se o catálogo de nós do motor é legível e se uma sessão PIE está no caminho. Cada verificação falha vem com a solução, então você nunca precisa adivinhar qual das seis coisas está errada. Código de saída 1 significa que o editor não pôde ser alcançado.

4. Registre o Servidor

Não escreva a configuração manualmente. Execute isto a partir do diretório do seu projeto e ele escreve os arquivos:

node mcp-server/dist/index.js --install-config

Isso escreve todos os clientes de escopo de projeto de uma vez — .mcp.json (Claude Code), .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json, .codex/config.toml — criando diretórios conforme necessário. Se um arquivo já existir, apenas a entrada unreal é tocada; servidores MCP que você já tinha são preservados, e um arquivo que não é JSON válido é recusado em vez de sobrescrito.

node mcp-server/dist/index.js --install-config --client cursor          # just one client
node mcp-server/dist/index.js --install-config --client claude-desktop  # global, per-user config
node mcp-server/dist/index.js --install-config --dir /path/to/project   # somewhere other than cwd

O Claude Desktop não faz parte da varredura e precisa ser nomeado, porque sua configuração é global e compartilhada com todos os outros projetos na máquina. Os locais dos arquivos e chaves raiz seguem o próprio ModelContextProtocol.GenerateClientConfig da Epic no UE 5.8, então são os que todo desenvolvedor Unreal será instruído a esperar.

--print-config ainda emite o JSON sem escrever nada, se você preferir colar:

node mcp-server/dist/index.js --print-config                      # Claude Desktop
node mcp-server/dist/index.js --print-config --client cursor      # Cursor
node mcp-server/dist/index.js --print-config --client claude-code # Claude Code

Ele emite o JSON exato para esta máquina, com caminhos absolutos já resolvidos, e informa em qual arquivo ele vai.

Isso existe porque a configuração do cliente é sua própria categoria de falha e tudo é autoinfligido: uma vírgula ausente quebra o arquivo inteiro, um caminho relativo silenciosamente não resolve, e no Windows um node simples pode não estar no PATH que o cliente usa. Cada um desses produz o mesmo sintoma — o servidor nunca inicia, sem explicação. A configuração impressa usa o caminho absoluto do Node que executou o comando, então não pode ser o errado.

Então saia completamente e reabra o cliente. Fechar a janela não é suficiente, e é o motivo mais comum pelo qual uma configuração correta parece não funcionar.

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

{
  "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.

O que o CI cobre, e o que não cobre

Status: o workflow está commitado, mas nunca foi executado. O GitHub se recusou a iniciá-lo — "o job não foi iniciado porque sua conta está bloqueada devido a um problema de cobrança" — então nenhum badge é mostrado aqui. Um badge lendo "falhando" por um motivo de cobrança diria algo falso sobre o código. O workflow é estruturalmente válido e toda a suíte é verificada para passar localmente sem nenhum editor em execução, que é a mesma coisa que faz em um runner; isso é uma afirmação sobre execuções locais, não um resultado de CI.

O badge acima cobre as partes que não precisam de instalação do Unreal, executadas em uma máquina Linux limpa sem nada pré-instalado: build, typecheck, paridade ferramenta/ponte, guardas de documentação, orçamentos de tokens de perfil, conformidade estrita de protocolo do cliente e os testes unitários — no Node mais antigo que o README promete e no atual. Também verifica que --doctor e --print-config se comportam corretamente sem nenhum editor em execução, já que é exatamente quando alguém os usa.

Ele não executa verificação ao vivo ou o benchmark de modelo local. Esses precisam de um editor em execução, e um precisa de GPU. Seus resultados estão em docs/LIVE_VERIFICATION.md e docs/LOCAL_MODEL_BENCHMARK.md, e são executados manualmente contra ambas as versões do motor. Reivindicá-los no CI tornaria o badge menos significativo do que é.

O plugin C++ também não é compilado no CI, porque a Epic não fornece um motor que possa ser buscado lá. npm run build:engines o compila contra cada motor configurado localmente e relata sucesso apenas se todos realmente compilaram.

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.