UnrealMCP Plugin

Um plugin não oficial para Unreal Engine que atua como servidor MCP, permitindo que ferramentas de IA controlem o motor remotamente.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Plugin UnrealMCP

REPOSITÓRIO EM FASE INICIAL (WIP)

Estou trabalhando para adicionar mais ferramentas e limpar o código agora, pretendo permitir extensão fácil de ferramentas fora do plugin principal

Isto é muito um trabalho em andamento, e preciso limpar muita coisa!!!!!

Além disso, só uso Windows, então não sei como isso seria configurado para Mac/Unix

Visão Geral

UnrealMCP é um plugin não oficial para Unreal Engine, projetado para controlar o Unreal Engine com ferramentas de IA. Ele implementa um Protocolo de Controle de Máquina (MCP) dentro do Unreal Engine, permitindo que sistemas de IA externos interajam e manipulem o ambiente Unreal programaticamente.

Só aprendi sobre MCP há alguns dias, então não estou muito familiarizado com isso, ainda estou aprendendo, então as coisas podem ser um pouco brutas inicialmente. Implementei isso usando https://github.com/ahujasid/blender-mcp como referência, que depende do Claude for Desktop. Agora funciona tanto com Claude for Desktop quanto com Cursor. Se você experimentar com outros modelos, por favor me avise!

⚠️ AVISO

Este plugin permite que agentes de IA modifiquem diretamente seu projeto Unreal Engine. Embora possa ser uma ferramenta poderosa, também traz riscos:

  • Agentes de IA podem fazer alterações inesperadas no seu projeto
  • Arquivos podem ser acidentalmente excluídos ou modificados
  • Configurações do projeto podem ser alteradas
  • Assets podem ser sobrescritos

MEDIDAS DE SEGURANÇA IMPORTANTES:

  1. Sempre use controle de versão (como Git ou Perforce) com seu projeto
  2. Faça backups regulares do seu projeto
  3. Teste o plugin em um projeto separado primeiro
  4. Revise as alterações antes de confirmá-las

Ao usar este plugin, você reconhece que:

  • Você é o único responsável por quaisquer alterações feitas no seu projeto
  • O autor do plugin não é responsável por danos, perda de dados ou problemas causados por agentes de IA
  • Você usa este plugin por sua conta e risco

Recursos

  • Implementação de servidor TCP para controle remoto do Unreal Engine
  • Protocolo de comandos baseado em JSON para integração com ferramentas de IA
  • Integração com a interface do editor para acesso fácil à funcionalidade MCP
  • Capacidades abrangentes de manipulação de cena
  • Scripts Python complementares para interação no lado do cliente

Roteiro

Estas são as ideias que tenho para desenvolvimento a partir de 14/03/2025 Não tenho certeza do que é possível ainda, em teoria qualquer coisa, mas depende de quão bom o LLM integrado é em utilizar essas ferramentas.

  • Operações básicas funcionando
  • Python funcionando
  • Materiais
  • Extensões de usuário (em andamento)
  • Ferramentas de assets
  • Blueprints
  • VFX Niagara
  • Metasound
  • Landscape (posso adiar isso porque a Epic mencionou que vai atualizar as ferramentas de landscape)
  • Ferramentas de modelagem
  • PCG

Requisitos

  • Unreal Engine 5.5 (só testei nesta versão, pode funcionar com versões anteriores, mas sem suporte oficial)
  • Ambiente de desenvolvimento C++ configurado para Unreal Engine
  • Python 3.7+ para scripts no lado do cliente
  • Modelo para executar os comandos, nos testes usei Claude for Desktop https://claude.ai/download

Pré-requisitos para executar

  • Instalação do Unreal Editor (testado com 5.3, mas deve funcionar em 5.0+)
  • Python 3.7+ (pode rodar com sua instalação Python existente)
  • LLM compatível com MCP (Claude for Desktop, Cursor, etc.)
  • Configuração: execute setup_unreal_mcp.bat na pasta MCP conforme instruções em MCP/README_MCP_SETUP.md

Início Rápido para Usuários do Cursor

Se você quiser usar UnrealMCP com Cursor, siga estes passos simples:

  1. Clone ou baixe este repositório como um zip
  2. Crie um novo Projeto Unreal, ou abra um existente
  3. Crie uma pasta "Plugins" no diretório do seu projeto se ela não existir
  4. Descompacte ou copie este repositório para a pasta Plugins
  5. Execute setup_cursor_mcp.bat na pasta MCP
  6. Abra seu projeto Unreal e habilite o plugin em Editar > Plugins (se ainda não estiver habilitado)
  7. Inicie o Cursor e peça para trabalhar com seu projeto Unreal

É isso! O script de configuração configurará automaticamente tudo o que for necessário para a integração com Cursor.

Instalação

  1. Clone ou baixe este repositório como um zip
  2. Crie um novo Projeto Unreal, ou abra um existente
  3. Crie uma pasta "Plugins" no diretório do seu projeto se ela não existir
  4. Descompacte ou copie este repositório para a pasta Plugins
  5. Configure o MCP
    • Execute o script setup_unreal_mcp.bat na pasta MCP (veja MCP/README_MCP_SETUP.md para detalhes)
    • Isso configurará o Python e seu assistente de IA (Claude for Desktop ou Cursor)
  6. Abra seu projeto Unreal, o plugin deve estar disponível no menu Plugins
  7. Se não estiver, habilite o plugin em Editar > Plugins
  8. Escolha seu assistente de IA preferido:
    • Para Claude for Desktop: siga as instruções na seção "Com Claude for Desktop" abaixo
    • Para Cursor: siga as instruções na seção "Com Cursor" abaixo

Com Claude for Desktop

Você precisará encontrar seu diretório de instalação do Claude for Desktop. Encontre claude_desktop_config.json e adicione uma entrada para que fique assim:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "unreal": {
            "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
            "args": []
        }
    }
}

Alternativamente, o script unreal_mcp_setup.bat deve fazer isso por você.

Para encontrar o caminho da sua instalação do Claude for Desktop, você pode ir em configurações e clicar em 'Editar Config' Isso geralmente está em

C:\Users\USERNAME\AppData\Roaming\Claude

Com Cursor

O Cursor deve ser configurado automaticamente se você executou o script de configuração com a opção Cursor. Se precisar configurar manualmente:

Windows: %APPDATA%\Cursor\User\settings.json

Adicione ou atualize as configurações com:

{
    "mcp": {
        "enabled": true,
        "servers": {
            "unreal": {
                "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
                "args": []
            }
        }
    }
}

Teste

Depois que tudo estiver configurado, você precisa iniciar o editor Unreal. Nota: Nada mais precisa ser iniciado ou configurado para executar a ponte MCP, ela será executada quando necessário.

Abra o Claude for Desktop ou Cursor, certifique-se de que as ferramentas foram habilitadas com sucesso, peça ao seu assistente de IA para trabalhar no Unreal.

Aqui estão alguns exemplos de prompts para tentar:

  • "Quais atores estão no nível atual?"
  • "Crie um cubo na posição (0, 0, 100)"
  • "Liste os comandos disponíveis que posso usar com o Unreal Engine"

Uso

No Editor Unreal

Uma vez que o plugin esteja habilitado, você encontrará os controles MCP no botão da barra de ferramentas do editor. image

image

O servidor TCP pode ser iniciado/parado a partir daqui. Verifique o log de saída sob o filtro de log LogMCP para informações adicionais.

Uma vez que o servidor esteja confirmado em execução no editor. Abra o Claude for Desktop, certifique-se de que as ferramentas foram habilitadas com sucesso, peça ao Claude para trabalhar no Unreal.

Atualmente, apenas operações básicas são suportadas: criar objetos, modificar suas transformações, obter informações da cena e executar scripts Python. O Claude comete muitos erros com Python do Unreal, pois acredito que não há muitos exemplos para isso, mas deixe-o rodar e ele geralmente resolve as coisas. Eu realmente gostaria de melhorar esse aspecto de como funciona, mas é uma fruta fácil de colher para adicionar funcionalidade ao Unreal.

Integração no Lado do Cliente

Use os scripts Python fornecidos no diretório MCP para conectar e controlar sua instância do Unreal Engine:

from unreal_mcp_client import UnrealMCPClient

# Connect to the Unreal MCP server
client = UnrealMCPClient("localhost", 13377)

# Example: Create a cube in the scene
client.create_object(
    class_name="StaticMeshActor",
    asset_path="/Engine/BasicShapes/Cube.Cube",
    location=(0, 0, 100),
    rotation=(0, 0, 0),
    scale=(1, 1, 1),
    name="MCP_Cube"
)

Referência de Comandos

O plugin suporta vários comandos para manipulação de cena:

  • get_scene_info: Recuperar informações sobre a cena atual
  • create_object: Gerar um novo objeto na cena
  • delete_object: Remover um objeto da cena
  • modify_object: Alterar propriedades de um objeto existente
  • execute_python: Executar comandos Python no ambiente Python do Unreal
  • E mais por vir...

Consulte a documentação no diretório Docs para uma referência completa de comandos.

Considerações de Segurança

  • O servidor MCP aceita conexões de qualquer cliente por padrão
  • Limite a exposição do servidor ao localhost para desenvolvimento
  • Valide todos os comandos recebidos para prevenir ataques de injeção

Solução de Problemas

  • Certifique-se de que o Unreal Engine está rodando com o plugin MCP.
  • Verifique os logs no Claude for Desktop para saída de stderr.
  • Entre em contato no discord, acabei de criá-lo, mas verificarei periodicamente Discord (Dreamatron Studios): https://discord.gg/abRftdSe

Estrutura do Projeto

  • Source/UnrealMCP/: Implementação principal do plugin
    • Private/: Arquivos de implementação interna
    • Public/: Arquivos de cabeçalho públicos
  • Content/: Assets do plugin
  • MCP/: Scripts Python do cliente e exemplos
  • Resources/: Ícones e outros recursos

Licença

Licença MIT

Copyright (c) 2025 kvick

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrição, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software é fornecido o façam, sujeito às seguintes condições:

O aviso de copyright acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA FORMA, DECORRENTE DE, FORA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.

Créditos

Obrigado aos testadores!!!

Contribuindo

Contribuições são bem-vindas, mas precisarei de algum tempo para entender as coisas e limpar primeiro, lol