Unity Editor MCP

Permite que assistentes de IA interajam diretamente com o Unity Editor para desenvolvimento de jogos e automação assistidos por IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Unity Editor MCP

⚠️ Este projeto está em beta e em desenvolvimento intenso. Recursos e APIs podem mudar. Use por sua conta e risco.

Unity Editor MCP (Model Context Protocol) permite que assistentes de IA como Claude e Cursor interajam diretamente com o Unity Editor, possibilitando desenvolvimento de jogos assistido por IA e automação.

🚀 Recursos Principais

🎮 Gerenciamento de GameObjects: Crie primitivas, modifique transformações, gerencie hierarquias e exclua objetos
🔧 Sistema de Componentes: Adicione, remova, modifique e liste componentes em GameObjects com controle total de propriedades
🎭 Fluxo de Trabalho com Prefabs: Edição completa em modo prefab - abra, modifique, salve e saia com gerenciamento de overrides
🔍 Busca Inteligente: Encontre GameObjects por nome, tag, camada ou tipo de componente com correspondência exata/parcial
📊 Análise de Cena: Analise a composição da cena, estatísticas de componentes e conexões de prefabs
🎯 Inspeção de Componentes: Obtenha valores de componentes, encontre objetos por componente, rastreie referências entre objetos
🎬 Controle de Cena: Crie, carregue, salve cenas, gerencie configurações de build e trabalhe com múltiplas cenas
🏃 Testes em Modo Play: Inicie, pause e pare o modo play, verifique o estado do editor e o status de compilação
🖼️ Captura de Tela: Tire screenshots da Game View ou Scene View com capacidades de análise
🎨 Gerenciamento de Assets: Crie e modifique prefabs, materiais, scripts com controle abrangente de propriedades
🖱️ Automação de UI: Interaja com elementos de UI do Unity programaticamente para testes e automação
📝 Integração com Console: Leia logs do console do Unity filtrados por tipo com recursos aprimorados de depuração
🔄 Operações do Editor: Atualize assets, execute itens de menu e acione recompilações

📌 O que há de novo

Pacote Unity 0.16.0

Menor, não patch: esta versão altera o contrato de uma ferramenta e adiciona uma dependência de pacote, que é o que o esquema 0.x aqui incrementa na versão menor (0.15.0 adicionou as ferramentas do Test Runner da mesma forma). O pacote do servidor Node é versionado independentemente e não foi alterado.

Quebra de compatibilidade

run_tests agora requer testMode. Passe "EditMode", "PlayMode" ou "EditAndPlayMode" explicitamente; não há padrão, porque PlayMode e EditAndPlayMode entram em modo play e acionam um recarregamento de domínio, e escolher silenciosamente isso para um chamador que queria EditMode era uma armadilha. Um servidor MCP mais antigo que este pacote falhará em toda chamada run_tests contra ele, com testMode is required, porque não envia o campo. Atualize o servidor Node (npx unity-editor-mcp@latest) junto com o pacote Unity.
Nova dependência de pacote: com.unity.ugui 2.0.0. As ferramentas de interação de UI referenciam tipos uGUI, então a dependência agora é declarada em vez de assumida. O Unity resolve automaticamente; um projeto que removeu deliberadamente o uGUI verá ele voltar.

Execuções de teste são honestas sobre seu próprio estado

get_test_results relata runStatus, runGuid, secondsSinceLastProgress e possiblyStale, e nunca muta o estado da execução - a sondagem não pode mais abandonar uma execução que era apenas lenta.
cancel_tests relata o que realmente aconteceu. Se a API do Test Runner não aceitar o cancelamento, a execução é deixada intacta e informada a você, em vez de relatar um cancelamento que nunca ocorreu.
run_tests aceita force: true, que agora genuinamente cancela a execução em andamento primeiro e se recusa a iniciar uma segunda quando o cancelamento não está disponível e a execução antiga não está comprovadamente encerrada. Duas execuções concorrentes relatando em um único conjunto de resultados não é mais alcançável.
Os resultados sobrevivem ao recarregamento de domínio que uma execução em PlayMode causa, e os resultados pós-recarregamento não são mais descartados por uma sondagem no meio da execução.

A ponte permanece responsiva enquanto a thread principal do editor está ocupada

ping e get_editor_state são respondidos na thread do socket a partir do estado em cache, e carregam mainThreadResponsive, mainThreadLastTickSecondsAgo, mainThreadInFlightCommand e mainThreadInFlightSeconds - para que um cliente possa ver no que o editor está travado e por quanto tempo.
Comandos que não podem ser atendidos dessa forma falham com um erro MAIN_THREAD_STALLED nomeando o comando em andamento em vez de travar até um timeout opaco. Um handler que segura a thread principal além do limite de 600s é relatado uma vez por handler, não uma vez por segundo.

Registro de instâncias

Entradas de registro cujo processo Unity não existe mais são removidas automaticamente, então editores que travaram ou foram fechados à força param de desacelerar a descoberta. Defina UNITY_MCP_DISABLE_REGISTRY_PRUNE=true para optar por não participar.
As entradas são gravadas atomicamente, e a porta do listener que o Unity realmente vinculou é republicada imediatamente após um recarregamento de domínio.

Solução de problemas

Uma caixa de diálogo modal aberta no Unity e um Editor em segundo plano limitado pelo App Nap do macOS ambos param o loop do editor e parecem exatamente como uma travada. Veja Comandos Travam ou Retornam MAIN_THREAD_STALLED para saber como diferenciá-los e o que fazer.

🚀 Início Rápido

Pré-requisitos

✅ Unity 2020.3 LTS ou mais recente
✅ Node.js 18.0.0 ou mais recente
✅ Claude Desktop ou Cursor

Instalação

📦 Passo 1: Instale o Pacote Unity

No Unity:

Abra Window → Package Manager
Clique em "+" → "Add package from git URL..."
Cole: https://github.com/ozankasikci/unity-editor-mcp.git?path=unity-editor-mcp
Clique em Add

✨ O Unity iniciará automaticamente a ponte MCP. Ela usa a porta 6400 quando disponível e recorre a uma porta local livre quando múltiplas instâncias do Unity estão abertas.

⚙️ Passo 2: Configure Seu Cliente MCP

Para Claude Desktop:

Adicione ao seu arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity-editor-mcp": {
      "command": "npx",
      "args": ["unity-editor-mcp@latest"]
    }
  }
}

Para Cursor:

Adicione a mesma configuração nas configurações MCP do Cursor

✅ Passo 3: Verifique a Conexão

Reinicie seu cliente MCP (Claude Desktop ou Cursor)
Verifique o Console do Unity para: [Unity Editor MCP] Client connected
Você está pronto para começar! 🎮

Múltiplas Instâncias do Unity

Unity Editor MCP agora descobre automaticamente projetos Unity em execução. Cada instância do Unity Editor grava uma entrada de registro interno em tempo de execução sob ~/.unity-editor-mcp/instances, incluindo caminho do projeto, ID do processo, porta, versão do Unity, versão do pacote, ID do workspace, metadados de worktree Git e timestamp de heartbeat. Você não edita este arquivo.

Quando o servidor MCP Node inicia, ele seleciona a instância do Unity nesta ordem:

UNITY_PORT ou --port, se fornecidos explicitamente
UNITY_MCP_INSTANCE_ID ou --instance
UNITY_PROJECT_PATH, UNITY_MCP_PROJECT_PATH ou --project
UNITY_MCP_WORKSPACE_ID ou --workspace-id
o projeto Unity inferido do diretório de trabalho atual
o ID de workspace estável inferido do diretório de trabalho atual
a única instância Unity MCP ativa, se exatamente uma existir

Para worktrees Git, o ID do workspace é armazenado nos metadados privados do worktree do Git via git rev-parse --git-path unity-editor-mcp/workspace-id. Para projetos não-Git, é armazenado sob Library/UnityEditorMCP/workspace-id. Não é gravado em arquivos de projeto Unity rastreados.

Se o servidor inferir um projeto/workspace Unity local do diretório de trabalho atual, ele exige uma correspondência exata de projeto ou workspace e não usa o fallback de instância única ativa. Se worktrees relacionados do mesmo repositório Git estiverem abertos, mas nenhum corresponder ao worktree atual, ele falha fechado com uma lista de candidatos WORKTREE_MISMATCH em vez de conectar silenciosamente. Para restaurar o fallback de conveniência antigo explicitamente, defina UNITY_MCP_ALLOW_SINGLE_INSTANCE_FALLBACK=true ou passe --allow-single-instance-fallback.

Para inspecionar a descoberta sem iniciar uma sessão MCP:

unity-editor-mcp doctor
unity-editor-mcp doctor --project /path/to/UnityProject
unity-editor-mcp doctor --workspace-id <workspace-id>
unity-editor-mcp doctor --instance <instance-id>
unity-editor-mcp doctor --allow-single-instance-fallback
unity-editor-mcp doctor --json

Ferramentas Disponíveis

Unity Editor MCP fornece 63 ferramentas abrangentes em 11 categorias para automação completa do Unity Editor:

Ferramentas de Sistema e Núcleo (3 ferramentas)

ping - Teste a conexão com o Unity Editor e verifique o status do servidor
read_logs - Leia logs do console do Unity com filtragem por tipo (Log, Warning, Error, etc.)
refresh_assets - Atualize assets do Unity e opcionalmente aguarde a compilação estabilizar

Gerenciamento de GameObjects (5 ferramentas)

create_gameobject - Crie GameObjects com primitivas, transformações, tags e camadas
find_gameobject - Encontre GameObjects por nome, tag, camada com correspondência de padrão
modify_gameobject - Modifique propriedades de GameObjects (transformação, nome, estado ativo, pai, etc.)
delete_gameobject - Exclua um ou múltiplos GameObjects com tratamento opcional de filhos
get_hierarchy - Obtenha hierarquia completa da cena com componentes e controle de profundidade

Sistema de Componentes (5 ferramentas)

add_component - Adicione componentes Unity a GameObjects com valores iniciais de propriedades
remove_component - Remova componentes de GameObjects com verificações de segurança (impede remoção de Transform)
modify_component - Modifique propriedades de componentes com suporte a propriedades aninhadas usando notação de ponto
list_components - Liste todos os componentes em um GameObject com informações de tipo e status de remoção
get_component_types - Descubra tipos de componentes disponíveis com filtragem por categoria e capacidade de adição

Gerenciamento de Cenas (5 ferramentas)

create_scene - Crie novas cenas com integração de configurações de build e carregamento automático
load_scene - Carregue cenas existentes em modo Single ou Additive
save_scene - Salve a cena atual com funcionalidade Salvar Como
list_scenes - Liste todas as cenas no projeto com filtragem e informações de configurações de build
get_scene_info - Obtenha informações detalhadas da cena incluindo contagens de GameObjects

Análise de Cena (5 ferramentas)

get_gameobject_details - Inspeção profunda de GameObjects com detalhes de componentes e hierarquia
analyze_scene_contents - Estatísticas abrangentes de cena, composição e métricas de desempenho
get_component_values - Obtenha todas as propriedades e valores de componentes específicos com metadados
find_by_component - Encontre GameObjects por tipo de componente com filtragem de escopo (cena/prefabs/todos)
get_object_references - Analise referências entre objetos incluindo hierarquia e conexões de assets

Gerenciamento de Assets (11 ferramentas)

create_prefab - Crie prefabs a partir de GameObjects ou modelos vazios com opções de sobrescrita
modify_prefab - Modifique prefabs existentes com alterações de propriedades e atualizações de instâncias
instantiate_prefab - Instancie prefabs em cenas com opções de transformação e parentesco
open_prefab - Abra prefabs no modo prefab do Unity para edição detalhada com foco e isolamento
exit_prefab_mode - Saia do modo prefab com opções de salvar/descartar alterações
save_prefab - Salve alterações de prefab no modo prefab ou aplique overrides de instância aos assets de prefab
create_material - Crie novos materiais com atribuição de shader e configuração de propriedades
modify_material - Modifique materiais existentes com alterações de shader e atualizações de propriedades
manage_asset_import_settings - Gerencie configurações de importação de assets do Unity (obter, modificar, aplicar presets, reimportar)
manage_asset_database - Gerencie operações do Asset Database do Unity (encontrar, informações, criar pastas, mover, copiar, excluir, atualizar)
analyze_asset_dependencies - Analise dependências de assets do Unity (obter dependências, dependentes, dependências circulares, assets não utilizados, impacto de tamanho)

Gerenciamento de Scripts (6 ferramentas)

create_script - Crie novos scripts C# com modelos e gerenciamento de namespaces
read_script - Leia o conteúdo de arquivos de script com informações de realce de sintaxe
update_script - Modifique scripts existentes com substituição de conteúdo e validação
delete_script - Exclua arquivos de script com verificação de dependências e confirmação
list_scripts - Liste todos os scripts no projeto com filtragem e metadados
validate_script - Valide a sintaxe de scripts e verifique erros de compilação

Controles de Modo Play (4 ferramentas)

play_game - Inicie o modo play do Unity para testes e interação
pause_game - Pause ou retome o modo play do Unity
stop_game - Pare o modo play do Unity e retorne ao modo de edição
get_editor_state - Obtenha o estado atual do editor Unity (modo play, pausa, status de compilação)

Automação de UI (5 ferramentas)

find_ui_elements - Localizar elementos de UI na hierarquia da cena com filtragem
click_ui_element - Simular cliques em elementos de UI (botões, alternadores, etc.)
get_ui_element_state - Obter estado detalhado do elemento de UI e capacidades de interação
set_ui_element_value - Definir valores para elementos de entrada de UI (controles deslizantes, campos de entrada, etc.)
simulate_ui_input - Executar sequências complexas de interação com UI

Operações do Editor (5 ferramentas)

execute_menu_item - Executar itens de menu do Unity programaticamente com verificações de segurança
clear_console - Limpar logs do console do Unity com filtragem opcional
enhanced_read_logs - Leitura avançada de logs com busca, filtragem e capacidades de exportação
capture_screenshot - Tirar capturas de tela da Visualização do Jogo ou da Visualização da Cena com resolução e codificação personalizadas
analyze_screenshot - Analisar conteúdo de capturas de tela com capacidades básicas de análise de imagem

Controle e Automação do Editor (9 ferramentas)

manage_tags - Gerenciar tags do projeto Unity (adicionar, remover, listar)
manage_layers - Gerenciar camadas do projeto Unity (adicionar, remover, listar, converter índice/nome)
manage_selection - Gerenciar seleção do Editor Unity (obter, definir, limpar, obter detalhes)
manage_windows - Gerenciar janelas do Editor Unity (listar, focar, obter estado)
manage_tools - Gerenciar ferramentas e plugins do Editor Unity (listar, ativar, desativar, atualizar)
start_compilation_monitoring - Iniciar monitoramento da compilação do Unity com detecção de erros em tempo real
stop_compilation_monitoring - Parar o monitoramento da compilação e obter o status final
get_compilation_state - Obter o estado atual da compilação do Unity e erros
wait_for_compilation - Aguardar a compilação/recarga de domínio do Unity estabilizar e retornar mensagens finais

Solução de Problemas

Problemas com o Listener TCP do Unity

Se você vir "Porta 6400 já está em uso":

Isso é esperado quando outra instância do Unity já possui a porta padrão
O pacote usará automaticamente uma porta local disponível como alternativa
A porta alternativa é mantida pelo restante da sessão e não é silenciosamente movida de volta para 6400 depois; o servidor Node segue o editor através do registro de instâncias (ID do processo e caminho do projeto), então o número da porta não precisa ser estável
Execute unity-editor-mcp doctor para ver qual projeto e porta serão selecionados

Uma porta fixa só importa se você optar por não usar a descoberta com UNITY_PORT / --port. Nesse caso, certifique-se de que a porta que você fixou é a que o Unity realmente vinculou, que unity-editor-mcp doctor informa.

Falha na Conexão

Certifique-se de que o Editor Unity está em execução com o pacote instalado
Verifique o console do Unity para mensagens de erro
Verifique se o servidor Node.js está em execução
Verifique se o caminho da configuração do seu cliente MCP é absoluto

Comandos Travam ou Retornam `MAIN_THREAD_STALLED`

Quase todas as ferramentas precisam ser executadas na thread principal do Unity, então elas só podem responder enquanto o loop do editor está funcionando. Quando o loop para, os comandos ficam na fila em vez de serem concluídos.

O que a ponte faz sobre isso:

ping e get_editor_state são respondidos na thread do socket a partir do estado em cache, então eles continuam funcionando enquanto a thread principal está travada. Ambos informam mainThreadResponsive, mainThreadLastTickSecondsAgo, mainThreadInFlightCommand e mainThreadInFlightSeconds — use-os para distinguir "Unity está congelado" de "a ponte está ocupada executando o comando que você acabou de enviar" e de "a ponte está fora do ar".
Comandos na fila falham com MAIN_THREAD_STALLED em vez de travar até o timeout do cliente. O erro nomeia o comando e há quanto tempo o loop está silencioso.
Um comando nosso de longa duração não é uma parada. Enquanto o editor está dentro de um dos nossos manipuladores (refresh_assets, uma importação grande, entrar no modo de reprodução), os comandos atrás dele continuam esperando, e o erro, se o teto de 600s for eventualmente atingido, nomeia o comando que está segurando a thread principal. Esse relatório acontece uma vez por manipulador travado, não uma vez por segundo, então comandos enfileirados atrás dele depois continuam esperando em vez de falharem a cada verificação do watchdog.

Causas comuns, em ordem de probabilidade:

Uma caixa de diálogo modal está aberta no Unity. Caixas de diálogo modais bloqueiam completamente o loop do editor; nada que a ponte faça pode acordá-lo. Traga o Unity para a frente e dispense a caixa de diálogo.
A janela do Editor está oculta ou totalmente obstruída no macOS, então o App Nap a limita e o loop funciona em ritmo lento. Desobstruir a janela resolve o problema. Se você precisar que o Unity continue funcionando enquanto oculto, você pode optar por desativar o App Nap você mesmo — isso é uma configuração de sistema aplicada pelo usuário, não algo que o pacote faz:
```
defaults write com.unity3d.UnityEditor5.x NSAppSleepDisabled -bool YES
```
Reinicie o Unity depois. (Verificado contra /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Info.plist; instalações mais antigas do Unity podem usar um identificador de pacote diferente, então verifique o seu antes de executar isso.)
Uma importação longa, compilação de script ou transição de modo de reprodução está em andamento. Aguarde; o comando é concluído quando o loop retoma.

Observe que pedir ao Unity para drenar sua fila da thread do socket apenas reduz a latência enquanto o loop está já em execução — não pode reiniciar um loop que parou.

Servidor Node.js Não Inicia

Certifique-se de ter o Node.js 18+ instalado: node --version
Execute npm install no diretório mcp-server
Verifique se há mensagens de erro no console

Contribuindo

Consulte CONTRIBUTING.md para diretrizes de desenvolvimento.

Licença

Licença MIT - consulte LICENSE para detalhes.

Unity Editor MCP

Documentação

Unity Editor MCP

🚀 Recursos Principais

📌 O que há de novo

Pacote Unity 0.16.0

🚀 Início Rápido

Pré-requisitos

Instalação

📦 Passo 1: Instale o Pacote Unity

⚙️ Passo 2: Configure Seu Cliente MCP

✅ Passo 3: Verifique a Conexão

Múltiplas Instâncias do Unity

Ferramentas Disponíveis

Ferramentas de Sistema e Núcleo (3 ferramentas)

Gerenciamento de GameObjects (5 ferramentas)

Sistema de Componentes (5 ferramentas)

Gerenciamento de Cenas (5 ferramentas)

Análise de Cena (5 ferramentas)

Gerenciamento de Assets (11 ferramentas)

Gerenciamento de Scripts (6 ferramentas)

Controles de Modo Play (4 ferramentas)

Automação de UI (5 ferramentas)

Operações do Editor (5 ferramentas)

Controle e Automação do Editor (9 ferramentas)

Solução de Problemas

Problemas com o Listener TCP do Unity

Falha na Conexão

Comandos Travam ou Retornam MAIN_THREAD_STALLED

Servidor Node.js Não Inicia

Contribuindo

Licença

Comandos Travam ou Retornam `MAIN_THREAD_STALLED`