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

Referência do unity-mcp-cli: instale o MCP, faça login, configure agentes de IA, abra o Unity headless e execute ferramentas e C# pelo terminal.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/unity/cli).

`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

```bash
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

```bash
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](https://ai-game.dev/pt-br/docs/wiki/unity/extensions).

| 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

### login

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](https://ai-game.dev/pt-br/docs/wiki/unity/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.

```bash
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.

```bash
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](https://www.npmjs.com/package/unity-mcp-cli).

## Páginas relacionadas

- [Instalação](https://ai-game.dev/pt-br/docs/wiki/unity/installation) e [Primeiros passos](https://ai-game.dev/pt-br/docs/wiki/unity/getting-started).
- [Configuração](https://ai-game.dev/pt-br/docs/wiki/unity/configuration#overrides) para as variáveis de ambiente que `open` define.
- A CLI do próprio aplicativo desktop, `gamedev`: [CLI do app](https://ai-game.dev/pt-br/docs/wiki/app/cli).

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/unity/cli

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/unity/cli