Como Conectar o Claude Code ao Unity MCP: Instalação e Configuração

O Que Este Guia Abrange

Siga estes cinco passos para conectar o Unity MCP a um projeto Unity local para que o Claude CLI possa operar, visualizar e depurar o editor—não apenas editar scripts no disco.

Ao terminar, você deverá ser capaz de:

• Importar o Unity MCP via Package Manager Add package from disk
• Completar a ativação do plugin (conta ou código de ativação—siga seu Mcp Panel)
• Iniciar o Unity MCP Server local (porta padrão 6589)
• Copiar o comando CLI do Quick setup, executá-lo no Claude CLI e confirmar a conexão MCP

Página de download: Unity MCP

Este guia usa o Claude CLI. Para o Gemini CLI, escolha o cliente correspondente no Quick setup e copie seu comando CLI da mesma forma.

Pré-requisitos

Item	Observações
Unity	2022.3+ / Unity 6 recomendado (siga as notas de suporte atuais para sua versão)
Pacote do plugin	Arquivo do Unity MCP baixado e descompactado
Ativação	Conta + senha do plugin, ou e-mail + código de ativação (conforme o Mcp Panel)
IDE de IA	Claude CLI (mesmo fluxo para o Gemini CLI)
Rede local	A ponte MCP geralmente roda em 127.0.0.1—não exponha a porta publicamente

Passo 1: Baixar o Unity MCP

Baixe o plugin no site ou na página de releases do fornecedor do Unity MCP:

Exemplo de página de download: https://www.vberai.com/game-engines/unity?ch=CQZLC2FG

Fluxo sugerido:

1. Abra a página de download e obtenha o arquivo do Unity MCP
2. Salve-o localmente e descompacte em uma pasta fixa (o próximo passo precisa do package.json dentro dela)
3. Confirme que package.json existe na pasta descompactada antes de abrir o Unity

Diferenças de licenciamento e edição variam por fornecedor—siga a documentação oficial deles.

Passo 2: Importar o pacote

1. Abra seu projeto Unity de destino
2. Menu Window → Package Manager
3. Clique em + no canto superior esquerdo do painel do Package Manager
4. Escolha Add package from disk
5. Selecione o arquivo package.json da pasta descompactada no Passo 1

Após uma importação bem-sucedida, o pacote Unity MCP deverá aparecer na lista do Package Manager.

Passo 3: Ativar o unity-mcp

1. Menu Window → Unity MCP → Mcp Panel
2. Na tela de ativação, faça uma das opções:
   • Entre com conta + senha
   • Ou insira e-mail + código de ativação
3. Após a ativação bem-sucedida, abra a página de configurações do MCP Server (próximo passo)

Sem ativação, o serviço geralmente não inicia. Confirme que sua conta ou código corresponde à versão do plugin que você instalou.

Passo 4: Iniciar o unity-mcp-server

1. Após a ativação, abra a página de configurações do Unity MCP Server
2. Ajuste conforme necessário:
   • Porta: padrão 6589
   • Idioma: corresponda à sua preferência de interface
   • Inicialização: siga as opções do painel (por exemplo, iniciar automaticamente com o editor, se disponível)
3. Clique em Start service
4. Quando o painel mostrar Running, o Unity MCP Server está ativo

Agora você tem uma ponte MCP local—em seguida, configure o Claude CLI.

Passo 5: Configurar o Claude CLI

1. Abra Tool management
   • Revise as ferramentas expostas pelo Unity MCP Server
   • Habilite apenas o que você deseja que o modelo use
2. Abra Quick setup
   • Escolha Claude CLI (Gemini CLI funciona da mesma forma—selecione esse cliente)
   • Claude CLI / Gemini CLI não suportam Auto configure—clique em Copy no CLI command exibido no painel

3. Abra um terminal do sistema, cole e execute o comando copiado (em um ambiente onde o Claude CLI esteja instalado)
4. Volte ao Claude CLI e confirme que unity-mcp (ou o nome registrado equivalente) aparece na lista de MCP

Verificação rápida após conectar

No Claude CLI, comece com uma verificação somente leitura, por exemplo:

Liste os objetos raiz na Hierarchy da cena atualmente aberta no Unity.

Se a resposta corresponder ao editor, a ponte está saudável. Em seguida, tente uma pequena escrita (crie um GameObject vazio temporário e exclua-o) para confirmar permissões e seleção de ferramentas.

FAQ

Add package from disk não encontra o package.json?
Confirme que o Passo 1 descompactou totalmente o arquivo e que você selecionou package.json na raiz dessa pasta—não uma extração aninhada.

A ativação continua falhando?
Verifique se sua conta ou código de ativação é válido, não expirou e está vinculado ao e-mail correto, depois tente novamente no Mcp Panel.

Iniciou o serviço mas não está Running?
Garanta que a porta 6589 (ou sua porta personalizada) esteja livre e que o localhost não esteja bloqueado. Confirme que a ativação do Passo 3 foi bem-sucedida.

O Claude CLI não mostra unity-mcp?
Confirme que o Unity ainda mostra Running; volte ao Quick setup, copie o comando CLI novamente e execute-o completamente no terminal. Certifique-se de ter escolhido Claude CLI, não Cursor. Para o Gemini CLI, escolha Gemini CLI e copie o comando desse cliente.

Próximos passos

• Tente uma consulta de cena em linguagem natural ou uma pequena edição para aprender os limites das ferramentas
• Faça commit antes de grandes alterações; mantenha a ponte apenas no localhost
• Padrões de prompt após conectar: Unity MCP com Claude Code e Cursor