Referência do unity-mcp-cli — Unity · AI Game Developer Wiki

unity-mcp-cli é a ferramenta de linha de comando do MCP para Unity. Ela instala o Unity e o plugin, faz login no ai-game.dev, grava configurações de agentes de IA, abre e fecha o Editor e chama ferramentas MCP ou executa C# no Editor a partir de um terminal ou de um script de CI. Esta página lista todos os comandos e flags da versão 1.6.2.

Instalação

npm install -g unity-mcp-cli

Ou execute qualquer comando sem instalar: npx unity-mcp-cli <command>. Requer Node.js ^20.19.0 ou >=22.12.0 e funciona no Windows, macOS e Linux. Os comandos que gerenciam editores usam a CLI do Unity Hub; se o Unity Hub não estiver instalado, a CLI o instala.

Opções globais, disponíveis em todos os comandos:

Opção	Descrição
`-v, --verbose`	Saída de diagnóstico detalhada
`-V, --version`	Mostra a versão da CLI
`--help`	Ajuda do comando

Em um terminal não interativo (CI), a CLI desativa spinners e cores automaticamente. A maioria dos comandos que recebe um caminho de projeto o aceita como argumento posicional ou como --path, e usa a pasta atual por padrão.

Uma sessão típica

unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame

Comandos de configuração do projeto

install-unity

Instala um Editor Unity por meio do Unity Hub. Sem argumento, instala a versão estável mais recente.

Argumento / opção	Descrição
`[version]`	Versão do Editor, por exemplo `6000.3.1f1`
`--path <path>`	Lê a versão necessária de um projeto existente

create-project

Cria um novo projeto Unity com o Editor: unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1.

Argumento / opção	Descrição
`[path]`	Onde criar o projeto (obrigatório, ou `--path`)
`--unity <version>`	Versão do Editor (padrão: a mais alta instalada)

install-plugin

Adiciona o registro com escopo do OpenUPM e com.ivanmurzak.unity.mcp ao Packages/manifest.json. Nunca faz downgrade de uma versão mais alta já instalada. A pasta precisa ser um projeto Unity.

Opção	Descrição
`[path]`	Projeto Unity (padrão: pasta atual)
`--plugin-version <version>`	Versão a instalar (padrão: a mais recente no OpenUPM)
`--with-server`	Também baixa o binário `gamedev-mcp-server` para esta máquina na pasta da própria CLI
`--server-version <version>`	Versão do servidor para `--with-server`
`--server-source <path-or-url>`	Instala o servidor a partir de um zip local ou de uma URL (offline ou CI; ignora a verificação de checksum)
`--enroll <code>`	Resgata um código de inscrição de equipe para uma credencial de plugin vinculada a este projeto
`--enroll-stdin`	Lê o código de inscrição do stdin, mantendo-o fora do histórico do shell
`--yes`	Confirma prompts, como a troca de conta durante `--enroll`

install-extension

Instala uma extensão oficial no Packages/manifest.json. Veja Extensões.

Argumento / opção	Descrição
`[id]`	Nome no catálogo (`Tilemap`) ou id do pacote (`com.ivanmurzak.unity.mcp.tilemap`)
`[path]`	Projeto Unity (padrão: pasta atual)
`--extension-version <version>`	Versão a instalar (padrão: a mais recente no OpenUPM)
`--list`	Lista as extensões instaláveis e sai (não precisa de projeto nem de rede)

remove-plugin

Remove com.ivanmurzak.unity.mcp do Packages/manifest.json e mantém os registros com escopo. Recebe [path] (obrigatório, ou --path).

configure

Mostra ou oculta ferramentas, prompts e recursos em UserSettings/AI-Game-Developer-Config.json. Um item oculto ainda é executado quando chamado pelo nome.

Opção	Descrição
`[path]`	Projeto Unity (obrigatório, ou `--path`)
`--list`	Imprime a configuração atual e sai
`--enable-tools <names>`, `--disable-tools <names>`	Mostra ou oculta ferramentas específicas (separadas por vírgula)
`--enable-all-tools`, `--disable-all-tools`	Mostra ou oculta todas as ferramentas
`--enable-prompts <names>`, `--disable-prompts <names>`	O mesmo para prompts
`--enable-all-prompts`, `--disable-all-prompts`	Todos os prompts
`--enable-resources <names>`, `--disable-resources <names>`	O mesmo para recursos
`--enable-all-resources`, `--disable-all-resources`	Todos os recursos
`--agent <id>`	Grava uma configuração de agente de IA pelo configurador do servidor gerenciado
`--url <url>`	URL do servidor passada junto com `--agent`

bootstrap-local

Fixa a configuração de um projeto no modo Custom (local) com uma URL de servidor e um token fornecidos. Idempotente.

Opção	Descrição
`[path]`	Projeto Unity (padrão: pasta atual)
`--url <url>`	URL do servidor MCP local (obrigatório)
`--token <token>`	Token bearer local (obrigatório)
`--dry-run`	Informa o que mudaria sem gravar

Comandos de login e de agentes de IA

Faz login no ai-game.dev com o fluxo de dispositivo OAuth do navegador e armazena a credencial em ~/.ai-game-dev/credentials.json. O plugin do Editor e o aplicativo desktop usam a mesma credencial. Se você já estiver conectado, ele encerra antecipadamente.

Opção	Descrição
`--project <path>`	Armazena a credencial em `<path>/.ai-game-dev/` em vez do armazenamento da máquina
`--force`	Faz login novamente mesmo que já exista uma credencial
`--tools-only`	Autoriza apenas as ferramentas do motor, para runners de CI; nenhuma credencial de agente é armazenada
`--yes`	Confirma uma troca de conta sem solicitar confirmação

setup-mcp

Grava a configuração MCP de um agente de IA, com a mesma saída de Configure na janela do Editor. Por padrão, a URL é fixada neste projeto (https://ai-game.dev/mcp/p/<pin>) e, para configurações Cloud HTTP, carrega a chave deste projeto quando você está conectado. Consulte Connecting AI clients.

Opção	Descrição
`[agent-id]`	Agente a configurar, por exemplo `claude-code`, `cursor`, `codex`
`[path]`	Projeto Unity (padrão: pasta atual)
`--transport <transport>`	`http` (padrão) ou `stdio`
`--url <url>`	Substituição da URL do servidor para `http`
`--token <token>`	Grava este Personal Access Token em vez da chave do projeto
`--oauth`	Grava uma configuração somente de URL; o agente faz login com seu próprio OAuth
`--regenerate-key`	Gera uma nova chave de projeto, reescreve as configurações e revoga a chave antiga
`--no-pin`	Usa o endpoint `https://ai-game.dev/mcp` sem fixação
`--list`	Lista os ids dos agentes e seus caminhos de configuração

setup-skills

Gera os arquivos de habilidades do agente por meio do Editor em execução. O Unity precisa estar aberto com o plugin conectado.

Opção	Descrição
`[agent-id]`	Agente para o qual gerar as habilidades
`[path]`	Projeto Unity (padrão: pasta atual)
`--url <url>`, `--token <token>`	Substituições de URL do servidor e token
`--timeout <ms>`	Tempo limite da requisição (padrão 60000)
`--list`	Lista os agentes e se eles oferecem suporte a habilidades

Comandos do Editor

open

Abre o projeto no Unity Editor e define as variáveis de ambiente de conexão do plugin a partir das opções informadas. O editor inicia de forma desanexada.

Opção	Descrição
`[path]`	Projeto Unity (padrão: pasta atual)
`--unity <version>`	Versão do Editor (padrão: a versão do projeto, depois a mais alta instalada)
`--editor-path <path>`	Executável do Editor explícito; ignora a descoberta pelo Unity Hub
`--no-connect`	Abre sem variáveis de conexão MCP
`--url <url>`	URL do servidor (define `UNITY_MCP_HOST`, o alias de `UNITY_MCP_CLOUD_URL`)
`--keep-connected`	Força a conexão ativada
`--token <token>`	Token do servidor local (define `UNITY_MCP_TOKEN`)
`--auth <option>`	Modo de autorização (define `UNITY_MCP_AUTH_OPTION`); esta versão aceita `none` ou `required`
`--tools <names>`	Ferramentas separadas por vírgula a exibir (define `UNITY_MCP_TOOLS`)
`--transport <method>`	`streamableHttp` ou `stdio`
`--start-server <value>`	`true` ou `false` para a inicialização automática do servidor local
`--headless`	Inicia sem janela (`-batchmode`, gráficos mantidos) e aguarda até que o servidor MCP responda
`--idle-timeout <seconds>`	Encerra após essa quantidade de segundos sem chamada de ferramenta, salvando antes as cenas e os assets alterados
`--ready-timeout <ms>`	Com `--headless`, por quanto tempo aguardar (padrão 300000)
`--no-auto-dismiss-launch-errors`	Não clicar em Ignore na caixa de diálogo "compile errors at launch" do Unity
`--launch-dismiss-timeout-ms <ms>`	Tempo total de observação dessa caixa de diálogo (padrão 30000)
`--launch-dismiss-poll-interval-ms <ms>`	Intervalo de polling da caixa de diálogo (padrão 1500)

Dispensar a caixa de diálogo de erros de inicialização exige permissão de Acessibilidade para o terminal no macOS e xdotool no Linux X11 (Wayland não é suportado).

close

Fecha o Editor do projeto de forma graciosa: unity-mcp-cli close ./MyGame --timeout 60 --force. Fechar um Editor que não está em execução é bem-sucedido.

Opção	Descrição
`[path]`	Projeto Unity (padrão: pasta atual)
`--timeout <seconds>`	Aguarda um encerramento educado (padrão 30)
`--force`	Encerra à força o Editor se ele não tiver fechado até então
`--owned-only`	Fecha apenas um Editor iniciado pela CLI (`exec`, `open --headless`)

wait-for-ready

Consulta repetidamente até que o Editor e o servidor MCP aceitem chamadas de ferramentas. Opções: [path], --url, --token, --timeout <ms> (padrão 120000) e --interval <ms> (padrão 3000).

status

Mostra se o Unity está em execução, se o servidor MCP local responde e se o servidor configurado (por exemplo, a nuvem) está acessível. Opções: [path], --url, --token, --timeout <ms> (padrão 5000).

Comandos de ferramentas

run-tool

Chama uma ferramenta MCP pela API HTTP do servidor. A URL e o token vêm da configuração do projeto (modo Custom ou Cloud), a menos que você os substitua.

unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw

Opção	Descrição
`<tool-name>`	Ferramenta a chamar
`[path]`	Projeto Unity, usado para configuração e detecção de porta
`--url <url>`, `--token <token>`	Substituições que ignoram a configuração
`--input <json>`, `--input-file <file>`	Argumentos da ferramenta (padrão `{}`)
`--raw`	Saída JSON bruta
`--timeout <ms>`	Tempo limite da requisição (padrão 60000)

run-system-tool

As mesmas opções de run-tool, para ferramentas de sistema que não são expostas aos clientes MCP (por exemplo, geração de skills e controle de sessão).

exec

Executa C# no Editor por meio de script-execute e imprime o resultado. Usa um Editor aberto, se houver; caso contrário, inicia um Editor headless que permanece aquecido para chamadas posteriores e encerra após --idle segundos.

unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec

Opção	Descrição
`[code]`	Instruções C#; a última expressão é o resultado (ou use `-f` ou stdin)
`--path <path>`	Projeto Unity (padrão: pasta atual)
`-f, --file <file>`	Lê o código de um arquivo (`-` para stdin)
`--using <namespace>`	Namespace extra, repetível
`--include <path>`	Arquivo ou pasta `.cs` auxiliar em `.ai-game-dev/snippets`, repetível
`--window`	Inicia o Editor com janela em vez de headless
`--idle <seconds>`	Tempo ocioso antes de um Editor iniciado por `exec` encerrar (padrão 300, 0 para nunca)
`--ready-timeout <ms>`	Espera pelo Editor (padrão 300000)
`--timeout <ms>`	Tempo limite da chamada da ferramenta
`--raw`	JSON bruto da resposta da ferramenta
`--url <url>`, `--token <token>`	Substituições

Um erro de compilação encerra com código 1 e aponta para as suas linhas.

Manutenção

update

Atualiza a CLI para a versão mais recente do npm. --check apenas verifica e encerra com código 2 quando há uma atualização disponível. Sob npx não há nada para atualizar.

Uso como biblioteca

O pacote também exporta uma API Node.js tipada (installPlugin, removePlugin, configure, setupMcp, installExtension e mais) que retorna objetos de resultado em vez de imprimir. Veja o README do pacote no npm.

Instalação e Primeiros passos.
Configuração para as variáveis de ambiente que open define.
A CLI do próprio aplicativo desktop, gamedev: CLI do app.

Instalação#

Uma sessão típica#

Comandos de configuração do projeto#

install-unity#

create-project#

install-plugin#

install-extension#

remove-plugin#

configure#

bootstrap-local#

Comandos de login e de agentes de IA#

login#

setup-mcp#

setup-skills#

Comandos do Editor#

open#

close#

wait-for-ready#

status#

Comandos de ferramentas#

run-tool#

run-system-tool#

exec#

Manutenção#

update#

Uso como biblioteca#

Páginas relacionadas#