# Referência da CLI — Unreal Engine · AI Game Developer Wiki

Referência completa do unreal-mcp-cli: instale o plugin Unreal MCP, faça login, configure agentes de IA, abra o editor e execute Python.

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

`unreal-mcp-cli` é a ferramenta de linha de comando do Unreal MCP. Ela instala e atualiza o plugin, faz login no ai-game.dev, grava configs MCP para agentes de IA, inicia o Unreal Editor com as configurações de conexão corretas e chama ferramentas a partir de scripts e CI. Funciona no Windows, macOS e Linux. Esta página cobre a versão 0.26.2.

## Instalar a CLI

Requer Node.js `^20.19.0` ou `>=22.12.0`.

```bash
npm install -g unreal-mcp-cli
unreal-mcp-cli --version
```

Ou execute um único comando sem instalar:

```bash
npx unreal-mcp-cli@latest status
```

Execute `unreal-mcp-cli <command> --help` para a ajuda integrada de qualquer comando. A flag global `-v, --verbose` imprime diagnósticos extras.

**Observação:** comandos que recebem o projeto como `[path]` o aceitam como argumento posicional. Comandos sem `[path]` o recebem com `-p, --path <dir>`. Ambos usam a pasta atual como padrão. Passar um caminho posicional para um comando `--path` falha com "too many arguments".

## Visão geral dos comandos

| Comando | Finalidade |
| --- | --- |
| `create-project <path>` | Cria a estrutura de um projeto C++ mínimo do Unreal Engine |
| `install-plugin [path]` | Instala o plugin UnrealMCP em `<project>/Plugins` |
| `update [path]` | Atualiza o plugin instalado |
| `remove-plugin [path]` | Remove o plugin |
| `install-extension <id> [path]` | Instala uma extensão do Unreal MCP |
| `login` | Faz login no ai-game.dev (fluxo de código de dispositivo) |
| `configure` | Grava valores `UNREAL_MCP_*` em `<project>/.env` |
| `setup-mcp [agent]` | Grava uma config MCP para um agente de IA |
| `setup-skills` | Grava uma skill do Claude Code para o projeto |
| `open [path]` | Inicia o Unreal Editor com as configurações de conexão |
| `close [path]` | Fecha o editor que está executando o projeto |
| `exec [code]` | Executa Python no editor |
| `status` | Mostra o estado do pacote, projeto, plugin e conexão |
| `wait-for-ready` | Aguarda até o servidor MCP do projeto responder |
| `run-tool <tool>` | Chama uma ferramenta MCP via HTTP |
| `run-system-tool <tool>` | Chama uma ferramenta de sistema via HTTP |
| `bootstrap-local [path]` | Compila a bridge a partir do código-fonte |
| `install-engine [version]` | Detecta engines instaladas, faz link com o Epic launcher |

## Comandos de configuração do projeto

### create-project

Cria a estrutura de um projeto C++ mínimo. Opções: `--name <name>` (nome do projeto e do módulo; letras, dígitos e underscores, sem hífens), `--engine <version>` (o `EngineAssociation`, por exemplo `5.7`), `--force` (permite uma pasta não vazia).

```bash
unreal-mcp-cli create-project ./MyGame --engine 5.7
```

### install-plugin

Instala o plugin. Sem um código-fonte local, baixa do release do GitHub o código-fonte do plugin correspondente à versão da CLI e verifica sua assinatura antes.

| Flag | Significado |
| --- | --- |
| `--version <v>` | Release do plugin a baixar (padrão: a versão da CLI) |
| `--plugin-source <dir>` | Usa uma pasta local do plugin (offline, CI, desenvolvimento) |
| `--junction` | Link em vez de cópia (Windows, para desenvolvimento do plugin) |
| `--with-server` | Também baixa o `gamedev-mcp-server` com checksum verificado |
| `--server-version <v>`, `--server-source <path-or-url>` | Versão do servidor, ou uma origem local ou personalizada, para `--with-server` |
| `--enroll <code>`, `--enroll-stdin` | Resgata um código de enrollment de agente em vez de fazer login pelo navegador |
| `--base-url <url>` | URL base de autenticação para `--enroll` |
| `-y, --yes` | Confirma a troca da máquina para outra conta |

### update

Ressincroniza o plugin instalado. Em uma mudança de versão, remove o `Intermediate/` obsoleto e os `Binaries/` de C++ para que o Unreal recompile do zero, mantendo a bridge incluída. Flags: `--version <v>`, `--plugin-source <dir>`, `--force` (reinstala a mesma versão), `--no-clean` (mantém o cache de build).

### remove-plugin

Remove `Plugins/UnrealMCP` do projeto. Sem opções.

### install-extension

Instala uma [extensão](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions), a habilita junto com seu plugin de engine no `.uproject`. Flags: `--version <x.y.z>`, `--source <dir>`, `--build` (compila agora), `--engine-root <dir>` (engine para `--build`), `--force`.

```bash
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --build
```

### bootstrap-local

Compila a bridge a partir do código-fonte em `<project>/Intermediate/UnrealMCP/` para checkouts de código-fonte; requer o SDK do .NET 9. Flags: `--repo-root <dir>`, `--plan` (apenas imprime o plano de build).

### install-engine

Lista as engines instaladas ou verifica uma versão específica. Nunca baixa uma engine; para uma versão ausente, fornece um link do Epic Games Launcher. Flags: `--manifest <path>` (`LauncherInstalled.dat` explícito), `--install`, `--yes`.

## Comandos de login e de agentes de IA

### login

Faz login com o fluxo OAuth de código de dispositivo e salva a credencial em `~/.ai-game-dev/credentials.json`, compartilhada por todas as ferramentas do AI Game Dev na máquina.

| Flag | Significado |
| --- | --- |
| `-p, --path <dir>` | Salva a credencial no `.env` desse projeto em vez do armazenamento da máquina |
| `--tools-only` | Cria uma credencial somente de ferramentas para runners de CI (o app não pode usá-la) |
| `-y, --yes` | Confirma a troca da máquina para outra conta |
| `--base-url <url>` | URL base de autenticação (padrão `https://ai-game.dev`) |
| `--timeout <ms>` | Timeout total de polling |

### configure

Grava valores `UNREAL_MCP_*` em `<project>/.env` e adiciona `.env` ao gitignore. Flags: `-p, --path`, `--mode <Cloud|Custom>`, `--host <url>`, `--cloud-url <url>`, `--token <token>`, `--auth <option>`, `--keep-connected`, `--tools <list>`, `--start-server`, `--transport <stdio|http>`, `--log-level <level>`, `--no-gitignore`.

Com `--agent <id>`, em vez disso, pede ao `gamedev-mcp-server` gerenciado que grave uma config de cliente fixada; as flags relacionadas são `--url`, `--server-version` e `--server-source`.

### setup-mcp

Grava uma entrada de config MCP para um agente. Veja [Conectando clientes de IA](https://ai-game.dev/pt-br/docs/wiki/unreal/connecting-ai-clients#setup-mcp) para a lista de agentes.

| Flag | Significado |
| --- | --- |
| `-p, --path <dir>` | Pasta do projeto |
| `--transport <t>` | `http` (padrão) ou `stdio` (baixa o servidor local) |
| `--url <url>` | URL do servidor explícita |
| `--token <token>` | Bearer token explícito; tem precedência sobre a chave do projeto |
| `--oauth` | Cloud: config apenas com URL, o próprio agente faz login |
| `--regenerate-key` | Cloud: cria uma nova chave de projeto e revoga a antiga |
| `--no-pin` | URL `/mcp` simples em vez de `/mcp/p/<pin>` fixada ao projeto |
| `--dry-run` | Imprime o snippet sem gravá-lo |
| `--list` | Lista os agentes suportados e os caminhos de config |

### setup-skills

Grava `.claude/skills/unreal-mcp/SKILL.md`. Flags: `-p, --path`, `--url`, `--token`, `--force` (sobrescreve).

## Comandos do editor

### open

Inicia o Unreal Editor e passa as configurações de conexão como variáveis de ambiente `UNREAL_MCP_*`. A engine vem do `EngineAssociation` do projeto; uma engine compilada a partir do código-fonte precisa de `--engine-root`.

| Flag | Significado |
| --- | --- |
| `--connection-mode <mode>` | `Custom` ou `Cloud`; apenas `--host` já implica Custom |
| `--host`, `--token`, `--auth`, `--tools`, `--transport` | Define a variável `UNREAL_MCP_*` correspondente |
| `--keep-connected`, `--start-server` | Define a variável correspondente como true |
| `--no-connect` | Não passa nenhuma variável `UNREAL_MCP_*` |
| `--headless` | Inicia um editor sem janela controlado pela CLI e aguarda até que ele esteja pronto |
| `--idle <seconds>`, `--url <url>` | Encerramento por inatividade e URL do servidor para um editor controlado pela CLI |
| `--engine-root <dir>` | Pasta da engine para builds a partir do código-fonte |
| `--no-build` | Pula o build pré-lançamento dos módulos nativos |
| `--no-auto-dismiss-startup-dialogs` | Deixa os prompts de inicialização do Unreal como estão |
| `--startup-dismiss-timeout-ms`, `--startup-dismiss-poll-interval-ms` | Ajusta a dispensa de prompts (padrões 12000 e 1000) |
| `--no-cache` | Redescobre o caminho da engine |

No Linux, a dispensa de prompts de inicialização funciona apenas no X11.

### close

Fecha o editor que está executando o projeto. Com `--owned-only`, fecha apenas um editor iniciado pela CLI (via `exec` ou `open --headless`), que salva e encerra; um editor aberto por você nunca é afetado. `--force` mata um editor controlado pela CLI que não encerra a tempo; `--token` substitui o bearer token.

### exec

Executa Python no editor por meio de `python-execute`. Reutiliza um editor em execução ou inicia um headless que renderiza fora da tela (para que os screenshots continuem funcionando) e encerra após um período sem chamadas de ferramentas.

```bash
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGame
```

Flags: `-p, --path`, `-f, --file <file>` (`-` para stdin), `--include <path>` (helpers de `.ai-game-dev/snippets`, repetível), `--window`, `--idle <seconds>` (padrão 300, 0 = nunca), `--ready-timeout <ms>`, `--timeout <ms>`, `--raw` (imprime a resposta JSON), `--url`, `--token`, `--engine-root`, `--no-build`. Os resultados são impressos em stdout; `print()` e linhas de log em stderr.

## Comandos de ferramentas e status

### status e wait-for-ready

`status` informa a CLI, o projeto, o plugin e a conexão, com uma sondagem de alcance ao vivo (`--no-probe` a pula). `wait-for-ready` bloqueia até o servidor responder a um ping (`--timeout`, padrão 120000 ms; `--interval`, padrão 2000 ms). Ambos aceitam `-p, --path`, `--url` e `--token`.

### run-tool e run-system-tool

Chama uma ferramenta pelo servidor MCP local do projeto:

```bash
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGame
```

Flags: `-p, --path`, `--url`, `--token`, `--input <json>`, `--input-file <file>` (`-` para stdin), `--timeout <ms>` (padrão 60000).

A mesma lógica está disponível como uma biblioteca tipada (`import { openProject, runTool } from 'unreal-mcp-cli'`), usada pelo [app AI Game Dev](https://ai-game.dev/pt-br/docs/wiki/app).

---

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

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