Servidor MCP para UE5

Um servidor MCP (Model Context Protocol) que conecta assistentes de IA ao editor do Unreal Engine 5, permitindo manipular diretamente níveis, atores, Blueprints e Animation Blueprints.

Por que um repositório independente?

Este servidor MCP fazia originalmente parte do plugin Martins Unreal Claude, mas foi transferido para um repositório próprio porque:

1. Escopo ampliado: o protocolo MCP é um padrão aberto, hoje compatível com vários provedores de IA.

2. Forks mais simples: desenvolvedores podem adaptar a ponte para outros serviços de IA sem precisar obter o plugin inteiro do Unreal.

3. Contribuições da comunidade: um repositório independente facilita receber contribuições de novos recursos, correções de bugs e suporte a outros clientes MCP.

Related MCP server: Unreal-MCP

Clientes de IA compatíveis

Este servidor usa o padrão Model Context Protocol e funciona com qualquer cliente compatível com MCP, incluindo:

• Claude Code (CLI)

• Aplicativo Claude Desktop

• OpenAI ChatGPT Desktop (suporte a MCP adicionado em março de 2025)

• Cursor (ambiente de desenvolvimento com IA)

• Replit (plataforma de programação com IA)

• Sourcegraph Cody

• Windsurf

• E qualquer outra ferramenta compatível com MCP

O protocolo foi doado à Linux Foundation em dezembro de 2025 e continua sendo amplamente adotado pela indústria de IA.

Importante: o que esta ferramenta é — e o que não é

Esta NÃO é uma ferramenta de “texto para jogo”. Ela não gera modelos 3D, texturas ou animações, nem substitui o trabalho de artistas, animadores e criadores de assets.

Esta ferramenta acelera o fluxo de trabalho de quem desenvolve com Unreal Engine. Ela ajuda a:

• Reduzir tarefas repetitivas de configuração: criar a estrutura inicial de Blueprints, configurar máquinas de estado e vinculações de entrada.

• Automatizar tarefas repetitivas no editor: gerar atores, definir propriedades e organizar níveis usando linguagem natural.

• Prototipar rapidamente: testar ideias descrevendo o que você quer, em vez de navegar pelos menus.

• Aprender UE5: consultar a documentação integrada da API durante o trabalho.

O objetivo é acelerar as partes mais tediosas do desenvolvimento de jogos para que você possa se concentrar no trabalho criativo que realmente importa.

Requisitos

• Node.js 18.0.0 ou superior

• Um endpoint HTTP que implemente a API REST esperada (padrão: http://localhost:3000)

Observação: este servidor MCP foi desenvolvido para funcionar com o plugin Martins Unreal Claude, mas pode ser adaptado para outros back-ends HTTP que implementem a mesma API.

Início rápido

1. Instalação

git clone https://github.com/SilvaneiMartins/ue5-mcp-bridge-martins.git
cd ue5-mcp-bridge-martins
npm install

2. Configure seu cliente MCP

Adicione a configuração a seguir à configuração do seu cliente MCP:

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/ue5-mcp-bridge-martins/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/ue5-mcp-bridge-martins/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

Outros clientes MCP: consulte a documentação do seu cliente para configurar um servidor MCP. Este servidor usa transporte stdio.

3. Use o servidor

Depois de conectar, você pode interagir com o Unreal Editor usando linguagem natural:

"Crie um Point Light na posição 0, 0, 500"
"Liste todos os StaticMeshActors do nível"
"Crie um novo Actor Blueprint chamado BP_Enemy"
"Adicione uma variável float chamada Health ao BP_Player"
"Crie uma máquina de estado chamada Locomotion no meu Animation Blueprint"

Ferramentas disponíveis

Conexão e contexto

Níveis e atores

Assets

Execução de scripts

Viewport

Blueprints

Animation Blueprints

Personagens

Materiais

Enhanced Input

Fila de tarefas assíncronas

Operações com Animation Blueprints

A ferramenta unreal_anim_blueprint_modify oferece controle abrangente sobre Animation Blueprints:

Operações com máquinas de estado

Operações com transições

Grafo de condições de transição

Inspeção de nós e pinos

Atribuição de animações

Operações em lote

Sistema de contexto do UE 5.7

O servidor inclui documentação integrada da API do UE 5.7 que pode ser consultada:

Categorias disponíveis

Uso

// Obter uma categoria específica
{ "category": "animation" }

// Pesquisar por palavras-chave
{ "query": "state machine transitions" }

// Listar todas as categorias
{}

Injeção automática de contexto

Ative a injeção automática de contexto definindo:

{
  "env": {
    "INJECT_CONTEXT": "true"
  }
}

Configuração

Solução de problemas

As ferramentas exibem “NOT CONNECTED”

• Verifique se o back-end HTTP está em execução e acessível.

• Confirme se a variável de ambiente UNREAL_MCP_URL aponta para o endpoint correto.

• Confira se o endpoint responde em /mcp/status.

Erros de stdin/stdout

• Verifique se o Node.js 18 ou superior está instalado e disponível no PATH.

• Execute npm install para instalar as dependências.

• Confirme se o caminho na configuração do cliente MCP aponta para o index.js correto.

Executar a suíte de testes

Este repositório inclui uma suíte de testes Vitest (87 testes) que valida o comportamento da ponte sem precisar de uma instância do Unreal Editor em execução:

npm install
npm test              # executa todos os testes
npm run test:watch    # executa em modo de observação
npm run test:coverage # executa com relatório de cobertura

Os testes simulam o servidor HTTP do Unreal e cobrem a conversão de esquemas, a lógica do cliente HTTP, o carregamento de contexto, a listagem de ferramentas e o roteamento de chamadas.

Contribuição

Contribuições são bem-vindas! Você pode:

• Adicionar suporte a configurações de outros clientes MCP.

• Melhorar a documentação de contexto do UE5.

• Corrigir bugs ou adicionar recursos.

• Enviar melhorias para a documentação.

Licença

MIT com requisito de atribuição — consulte LICENSE para obter os detalhes.

Créditos originais exigidos pela licença: este projeto deriva do UE5 MCP Server original. A licença exige que os seguintes créditos sejam mantidos:

• Projeto original: UE5 MCP Server

• Repositório original: https://github.com/SilvaneiMartins/ue5-mcp-bridge-martins

Divulgação exigida: se você usar este código em outro servidor MCP ou integração de IA, informe esse uso na documentação do seu projeto.

Links relacionados

• Plugin Martins Unreal Claude — plugin do Unreal Engine que fornece o back-end HTTP para este servidor MCP.

• Model Context Protocol — especificação do protocolo.

• GitHub do MCP — repositórios e SDKs oficiais.