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.

Related MCP server: Grimoire

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):

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:

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:

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:

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.