Unreal-Blender MCP

Um servidor unificado para controlar Blender e Unreal Engine por meio de agentes de IA.

GitHub
16
Experimente este MCPPatrocinado

Documentação

Unreal-Blender MCP

O Unreal-Blender MCP é um servidor unificado para controlar tanto o Blender quanto o Unreal Engine por meio de agentes de IA usando a abordagem MCP (Machine Control Protocol).

Visão Geral

Este projeto estende o framework blender-mcp para incluir suporte ao Unreal Engine, permitindo que agentes de IA como Claude e ChatGPT controlem simultaneamente ambas as plataformas por meio de uma única interface.

Informações sobre Submódulo

Este projeto inclui blender-mcp como um submódulo Git. Ao clonar o repositório, use os seguintes comandos:

# Clone with submodules
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git

# Or clone normally and then initialize submodules
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

Recursos

  • Controle Unificado: Servidor MCP único para controlar tanto o Blender quanto o Unreal Engine
  • Integração com Agentes de IA: Projetado para funcionar com Claude, ChatGPT e outros assistentes de IA
  • Recursos do Blender: Mantém toda a funcionalidade do blender-mcp, incluindo:
    • Manipulação de cenas
    • Criação e edição de objetos
    • Gerenciamento de materiais
    • Integração de assets PolyHaven
    • Geração de modelos Hyper3D Rodin
  • Recursos do Unreal Engine:
    • Criação e gerenciamento de níveis
    • Importação de assets
    • Execução de código Python
    • Manipulação de cenas
  • Estrutura de Extensão: Estenda facilmente tanto o addon do Blender quanto o servidor, mantendo compatibilidade com atualizações upstream

Arquitetura

O sistema consiste em três componentes principais:

  1. Servidor MCP: Hub central que se comunica com agentes de IA via SSE (Server-Sent Events) na porta 8000
  2. Addon do Blender: Servidor socket dentro do Blender na porta 8400 (padrão) ou 8401 (estendido)
  3. Plugin do Unreal: Servidor HTTP dentro do Unreal Engine na porta 8500
[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

Estrutura de Extensão

Este projeto usa uma abordagem de extensão para manter compatibilidade com alterações upstream:

  • Extensão do Addon do Blender: Estende o BlenderMCPServer original mantendo o código original intacto
  • Extensão do Servidor: Aprimora o servidor original com ferramentas adicionais e integração com o Unreal Engine
  • Ferramentas de Interface: Fornece utilitários para instalar, configurar e executar extensões

Essa abordagem permite atualizações fáceis dos projetos originais sem conflitos de código.

Guia Passo a Passo de Instalação e Configuração

Pré-requisitos

  • Python 3.10 ou posterior
  • Blender 3.0 ou posterior
  • Unreal Engine 5.0 ou posterior
  • Gerenciador de pacotes uv (instale com pip install uv se você não o tiver)

1. Clone o Repositório

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or if you already cloned without --recursive:
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. Configure o Ambiente Python

# Create a virtual environment and activate it
uv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install project dependencies
uv pip install -e .

3. Instale o Addon do Blender

Escolha UMA das seguintes opções:

Opção A: Addon Padrão (blender-mcp original)

  1. Abra o Blender
  2. Navegue até Editar > Preferências > Add-ons
  3. Clique no botão "Instalar..."
  4. Navegue e selecione o arquivo blender-mcp/addon.py
  5. Ative o addon "Interface: Blender MCP" (marque a caixa)

Opção B: Addon Estendido (Com recursos adicionais)

  1. Execute o script de instalação da extensão: 
    python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
  2. Abra o Blender
  3. Navegue até Editar > Preferências > Add-ons
  4. Encontre e ative o addon "Interface: Extended Blender MCP" (marque a caixa)

4. Instale o Plugin do Unreal Engine

  1. Localize a pasta UEPythonServer neste projeto
  2. Copie a pasta inteira para o diretório Plugins do seu projeto Unreal
    • Se o seu projeto não tiver um diretório Plugins, crie um
  3. Inicie o Unreal Engine com o seu projeto
  4. Navegue até Editar > Plugins no menu
  5. Encontre e ative o plugin Python Server
  6. Reinicie o Unreal Engine quando solicitado

5. Inicie o Servidor MCP

Escolha UMA das seguintes opções:

Opção A: Servidor Padrão

# Make sure your virtual environment is activated
python main.py

Opção B: Servidor Estendido (Mais recursos)

# Make sure your virtual environment is activated
python run_extended_server.py

# Optional: Customize server options
python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG

6. Ative a Conexão do Servidor do Blender

  1. Inicie o Blender (se ainda não estiver em execução)
  2. No viewport 3D, pressione N para abrir o painel lateral
  3. Selecione a aba apropriada:
    • "BlenderMCP" (se estiver usando o addon padrão)
    • "ExtBlenderMCP" (se estiver usando o addon estendido)
  4. Clique no botão "Start Server"
  5. Verifique se o servidor iniciou com sucesso (verifique a saída do console)

7. Verifique a Conexão do Unreal Engine

  1. Com o Unreal Engine em execução e o plugin ativado
  2. O servidor Python deve iniciar automaticamente
  3. Verifique o Log de Saída (Janela > Ferramentas de Desenvolvedor > Log de Saída) para ver mensagens
  4. O plugin do Unreal agora deve estar pronto para receber comandos

8. Conecte um Agente de IA

Opção A: Integre com o Claude para Desktop

Adicione o seguinte à configuração do Claude para Desktop:

{
    "mcpServers": {
        "unreal-blender": {
            "command": "uvx",
            "args": [
                "unreal-blender-mcp"
            ]
        },
        "unreal-blender-ext": {
            "command": "python",
            "args": [
                "/path/to/unreal-blender-mcp/run_extended_server.py"
            ]
        }
    }
}

Substitua /path/to/ pelo caminho real do seu projeto.

Opção B: Integre com o Cursor

  1. Abra as Configurações do Cursor

  2. Navegue até a seção MCP

  3. Adicione os seguintes comandos:

    • Servidor Padrão: uvx unreal-blender-mcp
    • Servidor Estendido: python /path/to/unreal-blender-mcp/run_extended_server.py

    Substitua /path/to/ pelo caminho real do seu projeto.

Opção C: Integre com Outras Ferramentas de IA

Consulte a documentação da sua ferramenta de IA para integração com servidores MCP e aponte-a para:

  • URL do Servidor MCP: http://localhost:8000 (ou porta personalizada, se especificada)

9. Testando o Sistema

Quando todos os componentes estiverem em execução:

  1. Use seu agente de IA para interagir com o Blender pedindo que ele:

    • Crie um cubo ou esfera simples
    • Modifique propriedades de objetos
    • Crie materiais

  2. Use seu agente de IA para interagir com o Unreal Engine pedindo que ele:

    • Crie um novo nível
    • Posicione assets
    • Modifique propriedades da cena

  3. Experimente operações mais complexas que envolvam ambas as plataformas trabalhando juntas

Solução de Problemas

Se você encontrar problemas:

  1. Verifique se todos os servidores estão em execução (MCP, Blender, Unreal)
  2. Verifique se as configurações de porta correspondem (padrão: 8000 para MCP, 8400/8401 para Blender, 8500 para Unreal)
  3. Verifique as saídas do console para mensagens de erro
  4. Reinicie os componentes na ordem correta: primeiro o servidor MCP, depois o Blender e, em seguida, o Unreal Engine

Para informações mais detalhadas sobre desenvolvimento e extensão do sistema, consulte o Documento do Projeto e o diretório workflow.

Comparação: Padrão vs Estendido

RecursoServidor PadrãoServidor Estendido
Controle do Blender✅✅
Controle do Unreal✅✅
Comandos Personalizados do Blender❌✅
Informações Aprimoradas da Cena❌✅
Detecção Automática de Recursos❌✅
Compatibilidade Upstream✅✅

Escolha o servidor padrão para funcionalidade básica ou o servidor estendido para recursos avançados.

Desenvolvimento

Consulte o Documento do Projeto e o diretório workflow para informações detalhadas de desenvolvimento.

Para estender este projeto:

  • Para adicionar novos recursos ao addon do Blender: Modifique src/unreal_blender_mcp/blender_addon/extended_addon.py
  • Para adicionar novas ferramentas ao servidor: Modifique src/unreal_blender_mcp/server_extension/extended_server.py

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

  • Este projeto é baseado no blender-mcp de Siddharth Ahuja.

Desenvolvimentos Futuros

As seguintes melhorias estão planejadas para versões futuras:

API Estruturada do Unreal Engine

Atualmente, a comunicação com o Unreal Engine depende principalmente da execução direta de código Python. Uma melhoria planejada é implementar uma API estruturada semelhante à integração do Blender:

  • Criar funções predefinidas para operações comuns do Unreal Engine
  • Implementar tratamento adequado de erros e validação
  • Melhorar a segurança limitando o escopo de execução
  • Aprimorar a estabilidade e previsibilidade das operações
  • Manter compatibilidade retroativa enquanto adiciona estrutura

Essa melhoria criará uma experiência mais consistente em ambos os motores e melhorará a confiabilidade geral do sistema. Consulte a documentação do workflow para mais detalhes sobre esse desenvolvimento planejado.