unreal-mcp-server

Servidor MCP (Model Context Protocol) que conecta o Claude ao Unreal Engine 5.8 através da Remote Control API oficial do motor — sem plugin C++ customizado, sem build extra.

Este servidor roda como um processo Python externo, à parte do Editor da Unreal, e conversa com ele por HTTP usando a API que já vem embutida no motor.

Como funciona

Claude  <--MCP (stdio)-->  unreal-mcp-server (Python)  <--HTTP-->  Unreal Editor (Remote Control API)

• O Claude fala MCP com este servidor.
• Este servidor traduz cada chamada em uma requisição HTTP para a Remote Control API do Editor (porta padrão 30010).
• Nenhuma modificação no projeto Unreal é necessária além de habilitar o plugin nativo.

Pré-requisitos

• Unreal Engine 5.8 (ou compatível) com o Editor aberto.
• Plugin Remote Control API habilitado: Edit → Plugins → busque "Remote Control" → marque Remote Control API → reinicie o Editor se solicitado.
• Confirme a porta em Project Settings → Plugins → Web Remote Control (padrão: 30010).
• Python 3.10+.

Instalação

git clone https://github.com/Jeanosasco/unreal-mcp-server.git
cd unreal-mcp-server
pip install -r requirements.txt

Configuração no cliente MCP (Claude)

Adicione ao seu mcp.json (ou configuração equivalente do cliente):

{
  "mcpServers": {
    "unreal": {
      "command": "python",
      "args": ["/caminho/completo/para/unreal-mcp-server/server.py"],
      "env": {
        "UNREAL_HOST": "127.0.0.1",
        "UNREAL_RC_PORT": "30010",
        "MESHY_API_KEY": "msy-sua-chave-aqui"
      }
    }
  }
}

Variáveis de ambiente (opcionais, exceto MESHY_API_KEY se for usar geração de modelos):

Variável	Padrão	Descrição
UNREAL_HOST	127.0.0.1	Host onde o Editor está escutando
UNREAL_RC_PORT	30010	Porta HTTP da Remote Control API
MESHY_API_KEY	(vazio)	Chave da API da Meshy, necessária apenas para as tools de geração de modelo 3D
MODEL_OUTPUT_DIR	./generated_models	Pasta local onde os modelos gerados são salvos antes do import

Ferramentas (tools) disponíveis

Núcleo — endpoints oficiais da Remote Control API

Estas seguem 1:1 a documentação oficial da Unreal 5.8 e são as mais confiáveis:

Tool	Descrição
unreal_status	Verifica se a API está acessível e lista as rotas expostas pelo Editor
unreal_call_function	Chama uma UFUNCTION em qualquer UObject vivo
unreal_get_property	Lê o valor de uma propriedade
unreal_set_property	Escreve o valor de uma propriedade (deve ser EditAnywhere, não EditConst)
unreal_describe_object	Lista propriedades e funções expostas em um objeto — use para descobrir o que existe antes de chamar call_function/set_property
unreal_search_assets	Busca no Asset Registry do projeto
unreal_batch	Executa múltiplas requisições em uma única chamada

Conveniência — construídas sobre EditorLevelLibrary

Estas chamam funções bem conhecidas do EditorLevelLibrary, mas não fazem parte da referência oficial da Remote Control API listada acima. Se alguma falhar no seu build do Editor, use unreal_describe_object em /Script/EditorScriptingUtilities.Default__EditorLevelLibrary para confirmar o nome exato da função/parâmetros na sua versão:

Tool	Descrição
unreal_list_level_actors	Lista todos os atores no nível aberto
unreal_spawn_actor	Instancia um ator de uma classe, em uma posição/rotação
unreal_destroy_actor	Remove um ator do nível
unreal_save_current_level	Salva o nível atual

Geração de modelos 3D via IA (Meshy)

Estas tools não são parte da Unreal em si — chamam a API da Meshy para gerar um modelo 3D a partir de texto, e depois usam a tool de import (best-effort, veja acima) para colocá-lo no projeto:

Tool	Descrição
unreal_generate_3d_model	Gera um modelo 3D a partir de um prompt de texto e baixa o arquivo (.fbx/.glb/etc.) na máquina onde este servidor roda. Não mexe na Unreal.
unreal_import_model	Importa um arquivo de mesh local para o Content Browser do projeto aberto
unreal_generate_and_place_model	Fluxo completo: gera o modelo, importa no projeto, e instancia como ator no nível aberto — tudo em uma chamada

Requer MESHY_API_KEY configurada. O fluxo de geração é assíncrono no lado da Meshy (preview → refine) e pode levar de 1 a 5 minutos.

Exemplo de uso

Com o Editor aberto e o plugin habilitado, peça ao Claude algo como:

"Verifique se a Unreal está conectada, depois liste todos os atores no nível atual."

O Claude vai chamar unreal_status e, em seguida, unreal_list_level_actors.

Ou, para gerar um modelo do zero:

"Gere um modelo 3D de uma torre de vigia em pedra desgastada e coloque no nível."

O Claude vai chamar unreal_generate_and_place_model, que encadeia geração (Meshy) → import → spawn.

Solução de problemas

• "Could not reach the Unreal Remote Control API" — confirme que o Editor está aberto, o plugin Remote Control API está habilitado, e a porta em env bate com a configurada no projeto.
• Erro HTTP 4xx/5xx em unreal_call_function/unreal_set_property — normalmente indica objectPath, functionName ou propertyName incorretos. Use unreal_describe_object para confirmar os nomes exatos antes de tentar de novo.
• Propriedade não aceita escrita — a propriedade precisa ser EditAnywhere e não pode ser EditConst na definição C++/Blueprint.
• Firewall/rede — a Remote Control API escuta apenas em HTTP simples; garanta que a porta não está bloqueada localmente se o servidor Python rodar em outra máquina.
• "No Meshy API key provided" — configure a variável MESHY_API_KEY no mcp.json ou no ambiente antes de usar unreal_generate_3d_model/unreal_generate_and_place_model.
• unreal_import_model falha — o import automatizado depende de AutomatedAssetImportSubsystem, que não faz parte da referência oficial da Remote Control API. Use unreal_describe_object em /Script/UnrealEd.Default__AutomatedAssetImportSubsystem para confirmar a assinatura exata na sua versão do Editor, ou arraste o arquivo manualmente para o Content Browser como alternativa.
• Geração da Meshy demorando/travando — o fluxo preview → refine costuma levar de 1 a 5 minutos; verifique seu saldo de créditos em https://www.meshy.ai caso a tarefa falhe com erro 402.

Roadmap

• [ ] Suporte ao endpoint /remote/object/event (assinatura de eventos em tempo real via WebSocket)
• [ ] Ferramentas de alto nível para geração procedural de níveis
• [ ] Testes automatizados contra uma instância headless do Editor
• [ ] Empacotamento via pipx/binário standalone
• [ ] Suporte a outros provedores de geração 3D (Tripo AI, Rodin/Hyper3D) como alternativa à Meshy

Licença

A definir.